tksbrokerapi.TKSBrokerAPI

   1# -*- coding: utf-8 -*-
   2# Author: Timur Gilmullin
   3
   4"""
   5**TKSBrokerAPI** is the trading platform for automation and simplifying the implementation of trading scenarios,
   6as well as working with Tinkoff Invest API server via the REST protocol. The TKSBrokerAPI platform may be used in two ways:
   7from the console, it has a rich keys and commands, or you can use it as Python module with `python import`.
   8
   9TKSBrokerAPI allows you to automate routine trading operations and implement your trading scenarios, or just receive
  10the necessary information from the broker. It is easy enough to integrate into various CI/CD automation systems.
  11
  12- **Open account for trading:** http://tinkoff.ru/sl/AaX1Et1omnH
  13- **TKSBrokerAPI module documentation:** https://tim55667757.github.io/TKSBrokerAPI/docs/tksbrokerapi/TKSBrokerAPI.html
  14- **See examples:** https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README_EN.md#Usage-examples
  15- **Used constants are in the TKSEnums module:** https://tim55667757.github.io/TKSBrokerAPI/docs/tksbrokerapi/TKSEnums.html
  16- **About Tinkoff Invest API:** https://tinkoff.github.io/investAPI/
  17- **Tinkoff Invest API documentation:** https://tinkoff.github.io/investAPI/swagger-ui/
  18"""
  19
  20# Copyright (c) 2022 Gilmillin Timur Mansurovich
  21#
  22# Licensed under the Apache License, Version 2.0 (the "License");
  23# you may not use this file except in compliance with the License.
  24# You may obtain a copy of the License at
  25#
  26#     http://www.apache.org/licenses/LICENSE-2.0
  27#
  28# Unless required by applicable law or agreed to in writing, software
  29# distributed under the License is distributed on an "AS IS" BASIS,
  30# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  31# See the License for the specific language governing permissions and
  32# limitations under the License.
  33
  34
  35import sys
  36import os
  37from argparse import ArgumentParser
  38from importlib.metadata import version
  39
  40from datetime import datetime, timedelta
  41from dateutil.tz import tzlocal, tzutc
  42from time import sleep
  43
  44import re
  45import json
  46import requests
  47import traceback as tb
  48from typing import Union
  49
  50from multiprocessing import cpu_count
  51from multiprocessing.pool import ThreadPool
  52import pandas as pd
  53
  54from TKSEnums import *  # A lot of constants from enums sections: https://tinkoff.github.io/investAPI/swagger-ui/
  55
  56from pricegenerator.PriceGenerator import PriceGenerator, uLogger  # This module has a lot of instruments to work with candles data. See docs here: https://github.com/Tim55667757/PriceGenerator
  57from pricegenerator.UniLogger import DisableLogger as PGDisLog  # Method for disable log from PriceGenerator
  58
  59import UniLogger as uLog  # Logger for TKSBrokerAPI
  60
  61
  62# --- Common technical parameters:
  63
  64PGDisLog(uLogger.handlers[0])  # Disable 3-rd party logging from PriceGenerator
  65uLogger = uLog.UniLogger  # init logger for TKSBrokerAPI
  66uLogger.level = 10  # debug level by default for TKSBrokerAPI module
  67uLogger.handlers[0].level = 20  # info level by default for STDOUT of TKSBrokerAPI module
  68
  69__version__ = "1.5"  # The "major.minor" version setup here, but build number define at the build-server only
  70
  71CPU_COUNT = cpu_count()  # host's real CPU count
  72CPU_USAGES = CPU_COUNT - 1 if CPU_COUNT > 1 else 1  # how many CPUs will be used for parallel calculations
  73
  74# --- Main constants:
  75
  76NANO = 0.000000001  # SI-constant nano = 10^-9
  77
  78
  79def NanoToFloat(units: str, nano: int) -> float:
  80    """
  81    Convert number in nano-view mode with string parameter `units` and integer parameter `nano` to float view. Examples:
  82
  83    `NanoToFloat(units="2", nano=500000000) -> 2.5`
  84
  85    `NanoToFloat(units="0", nano=50000000) -> 0.05`
  86
  87    :param units: integer string or integer parameter that represents the integer part of number
  88    :param nano: integer string or integer parameter that represents the fractional part of number
  89    :return: float view of number
  90    """
  91    return int(units) + int(nano) * NANO
  92
  93
  94def FloatToNano(number: float) -> dict:
  95    """
  96    Convert float number to nano-type view: dictionary with string `units` and integer `nano` parameters `{"units": "string", "nano": integer}`. Examples:
  97
  98    `FloatToNano(number=2.5) -> {"units": "2", "nano": 500000000}`
  99
 100    `FloatToNano(number=0.05) -> {"units": "0", "nano": 50000000}`
 101
 102    :param number: float number
 103    :return: nano-type view of number: `{"units": "string", "nano": integer}`
 104    """
 105    splitByPoint = str(number).split(".")
 106    frac = 0
 107
 108    if len(splitByPoint) > 1:
 109        if len(splitByPoint[1]) <= 9:
 110            frac = int("{}{}".format(
 111                int(splitByPoint[1]),
 112                "0" * (9 - len(splitByPoint[1])),
 113            ))
 114
 115    if (number < 0) and (frac > 0):
 116        frac = -frac
 117
 118    return {"units": str(int(number)), "nano": frac}
 119
 120
 121def GetDatesAsString(start: str = None, end: str = None) -> tuple:
 122    """
 123    Create tuple of date and time strings with timezone parsed from user-friendly date.
 124
 125    User dates format must be like: `%Y-%m-%d`, e.g. `2020-02-03` (3 Feb, 2020).
 126
 127    Example input: "2022-06-01" "2022-06-20" -> output: ("2022-06-01T00:00:00Z", "2022-06-20T23:59:59Z")
 128    An error exception will occur if input date has incorrect format.
 129
 130    If `start=None`, `end=None` then return dates from yesterday to the end of the day.
 131    If `start=some_date_1`, `end=None` then return dates from `some_date_1` to the end of the day.
 132    If `start=some_date_1`, `end=some_date_2` then return dates from start of `some_date_1` to end of `some_date_2`.
 133    Start day may be negative integer numbers: `-1`, `-2`, `-3` - how many days ago.
 134
 135    Also, you can use keywords for start if `end=None`:
 136    `today` (from 00:00:00 to the end of current day),
 137    `yesterday` (-1 day from 00:00:00 to 23:59:59),
 138    `week` (-7 day from 00:00:00 to the end of current day),
 139    `month` (-30 day from 00:00:00 to the end of current day),
 140    `year` (-365 day from 00:00:00 to the end of current day),
 141
 142    :return: tuple with 2 strings `(start, end)` dates in UTC ISO time format `%Y-%m-%dT%H:%M:%SZ` for OpenAPI.
 143             See date and time format here: `TKSEnums.TKS_DATE_TIME_FORMAT`.
 144             Example: `("2022-06-01T00:00:00Z", "2022-06-20T23:59:59Z")`. Second string is the end of the last day.
 145    """
 146    uLogger.debug("Input start day is [{}] (UTC), end day is [{}] (UTC)".format(start, end))
 147    s = datetime.now(tzutc()).replace(hour=0, minute=0, second=0, microsecond=0)  # start of the current day
 148    e = s.replace(hour=23, minute=59, second=59, microsecond=0)  # end of the current day
 149
 150    # time between start and the end of the current day:
 151    if start is None or start.lower() == "today":
 152        pass
 153
 154    # from start of the last day to the end of the last day:
 155    elif start.lower() == "yesterday":
 156        s -= timedelta(days=1)
 157        e -= timedelta(days=1)
 158
 159    # week (-7 day from 00:00:00 to the end of the current day):
 160    elif start.lower() == "week":
 161        s -= timedelta(days=6)  # +1 current day already taken into account
 162
 163    # month (-30 day from 00:00:00 to the end of current day):
 164    elif start.lower() == "month":
 165        s -= timedelta(days=29)  # +1 current day already taken into account
 166
 167    # year (-365 day from 00:00:00 to the end of current day):
 168    elif start.lower() == "year":
 169        s -= timedelta(days=364)  # +1 current day already taken into account
 170
 171    # -N days ago to the end of current day:
 172    elif start.startswith('-') and start[1:].isdigit():
 173        s -= timedelta(days=abs(int(start)) - 1)  # +1 current day already taken into account
 174
 175    # dates between start day at 00:00:00 and the end of the last day at 23:59:59:
 176    else:
 177        s = datetime.strptime(start, "%Y-%m-%d").replace(hour=0, minute=0, second=0, microsecond=0, tzinfo=tzutc())
 178        e = datetime.strptime(end, "%Y-%m-%d").replace(hour=23, minute=59, second=59, microsecond=0, tzinfo=tzutc()) if end is not None else e
 179
 180    # converting to UTC ISO time formatted with Z suffix for Tinkoff Open API:
 181    s = s.strftime(TKS_DATE_TIME_FORMAT)
 182    e = e.strftime(TKS_DATE_TIME_FORMAT)
 183
 184    uLogger.debug("Start day converted to UTC ISO format, with Z: [{}], and the end day: [{}]".format(s, e))
 185
 186    return s, e
 187
 188
 189class TinkoffBrokerServer:
 190    """
 191    This class implements methods to work with Tinkoff broker server.
 192
 193    Examples to work with API: https://tinkoff.github.io/investAPI/swagger-ui/
 194
 195    About `token`: https://tinkoff.github.io/investAPI/token/
 196    """
 197    def __init__(self, token: str, accountId: str = None, useCache: bool = True, defaultCache: str = "dump.json") -> None:
 198        """
 199        Main class init.
 200
 201        :param token: Bearer token for Tinkoff Invest API. It can be set from environment variable `TKS_API_TOKEN`.
 202        :param accountId: string with numeric user account ID in Tinkoff Broker. It can be found in broker's reports.
 203                          Also, this variable can be set from environment variable `TKS_ACCOUNT_ID`.
 204        :param useCache: use default cache file with raw data to use instead of `iList`.
 205                         True by default. Cache is auto-update if new day has come.
 206                         If you don't want to use cache and always updates raw data then set `useCache=False`.
 207        :param defaultCache: path to default cache file. `dump.json` by default.
 208        """
 209        if token is None or not token:
 210            try:
 211                self.token = r"{}".format(os.environ["TKS_API_TOKEN"])
 212                uLogger.debug("Bearer token for Tinkoff OpenAPI set up from environment variable `TKS_API_TOKEN`. See https://tinkoff.github.io/investAPI/token/")
 213
 214            except KeyError:
 215                uLogger.error("`--token` key or environment variable `TKS_API_TOKEN` is required! See https://tinkoff.github.io/investAPI/token/")
 216                raise Exception("Token required")
 217
 218        else:
 219            self.token = token  # highly priority than environment variable 'TKS_API_TOKEN'
 220            uLogger.debug("Bearer token for Tinkoff OpenAPI set up from class variable `token`")
 221
 222        if accountId is None or not accountId:
 223            try:
 224                self.accountId = r"{}".format(os.environ["TKS_ACCOUNT_ID"])
 225                uLogger.debug("Main account ID [{}] set up from environment variable `TKS_ACCOUNT_ID`".format(self.accountId))
 226
 227            except KeyError:
 228                uLogger.warning("`--account-id` key or environment variable `TKS_ACCOUNT_ID` undefined! Some of operations may be unavailable (overview, trading etc).")
 229
 230        else:
 231            self.accountId = accountId  # highly priority than environment variable 'TKS_ACCOUNT_ID'
 232            uLogger.debug("Main account ID [{}] set up from class variable `accountId`".format(self.accountId))
 233
 234        self.version = __version__  # duplicate here used TKSBrokerAPI main version
 235        """Current TKSBrokerAPI version: major.minor, but the build number define at the build-server only.
 236
 237        Latest version: https://pypi.org/project/tksbrokerapi/
 238        """
 239
 240        self.aliases = TKS_TICKER_ALIASES
 241        """Some aliases instead official tickers.
 242
 243        See also: `TKSEnums.TKS_TICKER_ALIASES`
 244        """
 245
 246        self.aliasesKeys = self.aliases.keys()  # re-calc only first time at class init
 247
 248        self.exclude = TKS_TICKERS_OR_FIGI_EXCLUDED  # some tickers or FIGIs raised exception earlier when it sends to server, that is why we exclude there
 249
 250        self.ticker = ""
 251        """String with ticker, e.g. `GOOGL`. Use alias for `USD000UTSTOM` simple as `USD`, `EUR_RUB__TOM` as `EUR` etc. More tickers aliases here: `TKSEnums.TKS_TICKER_ALIASES`.
 252
 253        See also: `SearchByTicker()`, `SearchInstruments()`.
 254        """
 255
 256        self.figi = ""
 257        """String with FIGI, e.g. ticker `GOOGL` has FIGI `BBG009S39JX6`.
 258
 259        See also: `SearchByFIGI()`, `SearchInstruments()`.
 260        """
 261
 262        self.depth = 1
 263        """Depth of Market (DOM) can be >= 1. Default: 1. It used with `--price` key to showing DOM with current prices for givens ticker or FIGI.
 264
 265        See also: `GetCurrentPrices()`.
 266        """
 267
 268        self.server = r"https://invest-public-api.tinkoff.ru/rest"
 269        """Tinkoff REST API server for real trade operations. Default: https://invest-public-api.tinkoff.ru/rest
 270
 271        See also: API method https://tinkoff.github.io/investAPI/#tinkoff-invest-api_1 and `SendAPIRequest()`.
 272        """
 273
 274        uLogger.debug("Broker API server: {}".format(self.server))
 275
 276        self.timeout = 15
 277        """Server operations timeout in seconds. Default: `15`.
 278
 279        See also: `SendAPIRequest()`.
 280        """
 281
 282        self.headers = {
 283            "Content-Type": "application/json",
 284            "accept": "application/json",
 285            "Authorization": "Bearer {}".format(self.token),
 286            "x-app-name": "Tim55667757.TKSBrokerAPI",
 287        }
 288        """Headers which send in every request to broker server. Please, do not change it! Default: `{"Content-Type": "application/json", "accept": "application/json", "Authorization": "Bearer {your_token}"}`.
 289
 290        See also: `SendAPIRequest()`.
 291        """
 292
 293        self.body = None
 294        """Request body which send to broker server. Default: `None`.
 295
 296        See also: `SendAPIRequest()`.
 297        """
 298
 299        self.moreDebug = False
 300        """Enables more debug information in this class, such as net request and response headers in all methods. `False` by default."""
 301
 302        self.historyFile = None
 303        """Full path to the output file where history candles will be saved or updated. Default: `None`, it mean that returns only Pandas DataFrame.
 304
 305        See also: `History()`.
 306        """
 307
 308        self.htmlHistoryFile = "index.html"
 309        """Full path to the html file where rendered candles chart stored. Default: `index.html`.
 310
 311        See also: `ShowHistoryChart()`.
 312        """
 313
 314        self.instrumentsFile = "instruments.md"
 315        """Filename where full available to user instruments list will be saved. Default: `instruments.md`.
 316
 317        See also: `ShowInstrumentsInfo()`.
 318        """
 319
 320        self.searchResultsFile = "search-results.md"
 321        """Filename with all found instruments searched by part of its ticker, FIGI or name. Default: `search-results.md`.
 322
 323        See also: `SearchInstruments()`.
 324        """
 325
 326        self.pricesFile = "prices.md"
 327        """Filename where prices of selected instruments will be saved. Default: `prices.md`.
 328
 329        See also: `GetListOfPrices()`.
 330        """
 331
 332        self.infoFile = "info.md"
 333        """Filename where prices of selected instruments will be saved. Default: `prices.md`.
 334
 335        See also: `ShowInstrumentsInfo()`, `RequestBondCoupons()` and `RequestTradingStatus()`.
 336        """
 337
 338        self.bondsXLSXFile = "ext-bonds.xlsx"
 339        """Filename where wider Pandas DataFrame with more information about bonds: main info, current prices, 
 340        bonds payment calendar, some statistics will be stored. Default: `ext-bonds.xlsx`.
 341
 342        See also: `ExtendBondsData()`.
 343        """
 344
 345        self.calendarFile = "calendar.md"
 346        """Filename where bonds payment calendar will be saved. Default: `calendar.md`.
 347        
 348        Pandas dataframe with only bonds payment calendar also will be stored to default file `calendar.xlsx`.
 349
 350        See also: `CreateBondsCalendar()`, `ShowBondsCalendar()`, `ShowInstrumentInfo()`, `RequestBondCoupons()` and `ExtendBondsData()`.
 351        """
 352
 353        self.overviewFile = "overview.md"
 354        """Filename where current portfolio, open trades and orders will be saved. Default: `overview.md`.
 355
 356        See also: `Overview()`, `RequestPortfolio()`, `RequestPositions()`, `RequestPendingOrders()` and `RequestStopOrders()`.
 357        """
 358
 359        self.overviewDigestFile = "overview-digest.md"
 360        """Filename where short digest of the portfolio status will be saved. Default: `overview-digest.md`.
 361
 362        See also: `Overview()` with parameter `details="digest"`.
 363        """
 364
 365        self.overviewPositionsFile = "overview-positions.md"
 366        """Filename where only open positions, without everything else will be saved. Default: `overview-positions.md`.
 367
 368        See also: `Overview()` with parameter `details="positions"`.
 369        """
 370
 371        self.overviewOrdersFile = "overview-orders.md"
 372        """Filename where open limits and stop orders will be saved. Default: `overview-orders.md`.
 373
 374        See also: `Overview()` with parameter `details="orders"`.
 375        """
 376
 377        self.overviewAnalyticsFile = "overview-analytics.md"
 378        """Filename where only the analytics section and the distribution of the portfolio by various categories will be saved. Default: `overview-analytics.md`.
 379
 380        See also: `Overview()` with parameter `details="analytics"`.
 381        """
 382
 383        self.reportFile = "deals.md"
 384        """Filename where history of deals and trade statistics will be saved. Default: `deals.md`.
 385
 386        See also: `Deals()`.
 387        """
 388
 389        self.withdrawalLimitsFile = "limits.md"
 390        """Filename where table of funds available for withdrawal will be saved. Default: `limits.md`.
 391
 392        See also: `OverviewLimits()` and `RequestLimits()`.
 393        """
 394
 395        self.userInfoFile = "user-info.md"
 396        """Filename where all available user's data (`accountId`s, common user information, margin status and tariff connections limit) will be saved. Default: `user-info.md`.
 397
 398        See also: `OverviewUserInfo()`, `RequestAccounts()`, `RequestUserInfo()`, `RequestMarginStatus()` and `RequestTariffLimits()`.
 399        """
 400
 401        self.userAccountsFile = "accounts.md"
 402        """Filename where simple table with all available user accounts (`accountId`s) will be saved. Default: `accounts.md`.
 403
 404        See also: `OverviewAccounts()`, `RequestAccounts()`.
 405        """
 406
 407        self.iListDumpFile = "dump.json" if defaultCache is None or not isinstance(defaultCache, str) or not defaultCache else defaultCache
 408        """Filename where raw data about shares, currencies, bonds, etfs and futures will be stored. Default: `dump.json`.
 409
 410        Pandas dataframe with raw instruments data also will be stored to default file `dump.xlsx`.
 411
 412        See also: `DumpInstruments()` and `DumpInstrumentsAsXLSX()`.
 413        """
 414
 415        self.iList = None  # init iList for raw instruments data
 416        """Dictionary with raw data about shares, currencies, bonds, etfs and futures from broker server. Auto-updating and saving dump to the `iListDumpFile`.
 417        
 418        See also: `Listing()`, `DumpInstruments()`.
 419        """
 420
 421        # trying to re-load raw instruments data from file `iListDumpFile` or try to update it from server:
 422        if useCache:
 423            if os.path.exists(self.iListDumpFile):
 424                dumpTime = datetime.fromtimestamp(os.path.getmtime(self.iListDumpFile)).astimezone(tzutc())  # dump modification date and time
 425                curTime = datetime.now(tzutc())
 426
 427                if (curTime.day > dumpTime.day) or (curTime.month > dumpTime.month) or (curTime.year > dumpTime.year):
 428                    uLogger.warning("Local cache may be outdated! It has last modified [{}] UTC. Updating from broker server, wait, please...".format(dumpTime.strftime(TKS_PRINT_DATE_TIME_FORMAT)))
 429
 430                    self.DumpInstruments(forceUpdate=True)  # updating self.iList and dump file
 431
 432                else:
 433                    self.iList = json.load(open(self.iListDumpFile, mode="r", encoding="UTF-8"))  # load iList from dump
 434
 435                    uLogger.debug("Local cache with raw instruments data is used: [{}]. Last modified: [{}] UTC".format(
 436                        os.path.abspath(self.iListDumpFile),
 437                        dumpTime.strftime(TKS_PRINT_DATE_TIME_FORMAT),
 438                    ))
 439
 440            else:
 441                uLogger.warning("Local cache with raw instruments data not exists! Creating new dump, wait, please...")
 442                self.DumpInstruments(forceUpdate=True)  # updating self.iList and creating default dump file
 443
 444        else:
 445            self.iList = self.Listing()  # request new raw instruments data from broker server
 446            self.DumpInstruments(forceUpdate=False)  # save raw instrument's data to default dump file `iListDumpFile`
 447
 448        self.priceModel = PriceGenerator()  # init PriceGenerator object to work with candles data
 449        """PriceGenerator object to work with candles data: load, render interact and non-interact charts and so on.
 450
 451        See also: `LoadHistory()`, `ShowHistoryChart()` and the PriceGenerator project: https://github.com/Tim55667757/PriceGenerator
 452        """
 453
 454    def _ParseJSON(self, rawData="{}") -> dict:
 455        """
 456        Parse JSON from response string.
 457
 458        :param rawData: this is a string with JSON-formatted text.
 459        :return: JSON (dictionary), parsed from server response string.
 460        """
 461        responseJSON = json.loads(rawData) if rawData else {}
 462
 463        if self.moreDebug:
 464            uLogger.debug("JSON formatted raw body data of response:\n{}".format(json.dumps(responseJSON, indent=4)))
 465
 466        return responseJSON
 467
 468    def SendAPIRequest(self, url: str, reqType: str = "GET", retry: int = 3, pause: int = 5) -> dict:
 469        """
 470        Send GET or POST request to broker server and receive JSON object.
 471
 472        self.header: must be defining with dictionary of headers.
 473        self.body: if define then used as request body. None by default.
 474        self.timeout: global request timeout, 15 seconds by default.
 475        :param url: url with REST request.
 476        :param reqType: send "GET" or "POST" request. "GET" by default.
 477        :param retry: how many times retry after first request if an 5xx server errors occurred.
 478        :param pause: sleep time in seconds between retries.
 479        :return: response JSON (dictionary) from broker.
 480        """
 481        if reqType not in ("GET", "POST"):
 482            uLogger.error("You can define request type: 'GET' or 'POST'!")
 483            raise Exception("Incorrect value")
 484
 485        if self.moreDebug:
 486            uLogger.debug("Request parameters:")
 487            uLogger.debug("    - REST API URL: {}".format(url))
 488            uLogger.debug("    - request type: {}".format(reqType))
 489            uLogger.debug("    - headers:\n{}".format(str(self.headers).replace(self.token, "*** request token ***")))
 490            uLogger.debug("    - body:\n{}".format(self.body))
 491
 492        # fast hack to avoid all operations with some tickers/FIGI
 493        responseJSON = {}
 494        oK = True
 495        for item in self.exclude:
 496            if item in url:
 497                if self.moreDebug:
 498                    uLogger.warning("Do not execute operations with list of this tickers/FIGI: {}".format(str(self.exclude)))
 499
 500                oK = False
 501                break
 502
 503        if oK:
 504            counter = 0
 505            response = None
 506            errMsg = ""
 507
 508            while not response and counter <= retry:
 509                if reqType == "GET":
 510                    response = requests.get(url, headers=self.headers, data=self.body, timeout=self.timeout)
 511
 512                if reqType == "POST":
 513                    response = requests.post(url, headers=self.headers, data=self.body, timeout=self.timeout)
 514
 515                if self.moreDebug:
 516                    uLogger.debug("Response:")
 517                    uLogger.debug("    - status code: {}".format(response.status_code))
 518                    uLogger.debug("    - reason: {}".format(response.reason))
 519                    uLogger.debug("    - body length: {}".format(len(response.text)))
 520                    uLogger.debug("    - headers:\n{}".format(response.headers))
 521
 522                # Server returns some headers:
 523                # - `x-ratelimit-limit` - shows the settings of the current user limit for this method.
 524                # - `x-ratelimit-remaining` - the number of remaining requests of this type per minute.
 525                # - `x-ratelimit-reset` - time in seconds before resetting the request counter.
 526                # See: https://tinkoff.github.io/investAPI/grpc/#kreya
 527                if "x-ratelimit-remaining" in response.headers.keys() and response.headers["x-ratelimit-remaining"] == "0":
 528                    rateLimitWait = int(response.headers["x-ratelimit-reset"])
 529                    uLogger.debug("Rate limit exceeded. Waiting {} sec. for reset rate limit and then repeat again...".format(rateLimitWait))
 530                    sleep(rateLimitWait)
 531
 532                # Error status codes: https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
 533                if 400 <= response.status_code < 500:
 534                    msg = "status code: [{}], response body: {}".format(response.status_code, response.text)
 535                    uLogger.debug("    - not oK, but do not retry for 4xx errors, {}".format(msg))
 536                    counter = retry + 1
 537
 538                if 500 <= response.status_code < 600:
 539                    errMsg = "status code: [{}], response body: {}".format(response.status_code, response.text)
 540                    uLogger.debug("    - not oK, {}".format(errMsg))
 541                    counter += 1
 542
 543                    if counter <= retry:
 544                        uLogger.debug("Retry: [{}]. Wait {} sec. and try again...".format(counter, pause))
 545                        sleep(pause)
 546
 547            responseJSON = self._ParseJSON(rawData=response.text)
 548
 549            if errMsg:
 550                uLogger.error("Server returns not `oK` status! See: https://tinkoff.github.io/investAPI/errors/")
 551                uLogger.error("    - not oK, {}".format(errMsg))
 552
 553        return responseJSON
 554
 555    def _IUpdater(self, iType: str) -> tuple:
 556        """
 557        Request instrument by type from server. See available API methods for instruments:
 558        Currencies: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_Currencies
 559        Shares: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_Shares
 560        Bonds: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_Bonds
 561        Etfs: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_Etfs
 562        Futures: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_Futures
 563
 564        :param iType: type of the instrument, it must be one of supported types in TKS_INSTRUMENTS list.
 565        :return: tuple with iType name and list of available instruments of current type for defined user token.
 566        """
 567        result = []
 568
 569        if iType in TKS_INSTRUMENTS:
 570            uLogger.debug("Requesting available [{}] list. Wait, please...".format(iType))
 571
 572            # all instruments have the same body in API v2 requests:
 573            self.body = str({"instrumentStatus": "INSTRUMENT_STATUS_UNSPECIFIED"})  # Enum: [INSTRUMENT_STATUS_UNSPECIFIED, INSTRUMENT_STATUS_BASE, INSTRUMENT_STATUS_ALL]
 574            instrumentURL = self.server + r"/tinkoff.public.invest.api.contract.v1.InstrumentsService/{}".format(iType)
 575            result = self.SendAPIRequest(instrumentURL, reqType="POST")["instruments"]
 576
 577        return iType, result
 578
 579    def _IWrapper(self, kwargs):
 580        """
 581        Wrapper runs instrument's update method `_IUpdater()`.
 582        It's a workaround for using multiprocessing with kwargs. See: https://stackoverflow.com/a/36799206
 583        """
 584        return self._IUpdater(**kwargs)
 585
 586    def Listing(self) -> dict:
 587        """
 588        Gets JSON with raw data about shares, currencies, bonds, etfs and futures from broker server.
 589
 590        :return: Dictionary with all available broker instruments: currencies, shares, bonds, etfs and futures.
 591        """
 592        uLogger.debug("Requesting all available instruments for current account. Wait, please...")
 593        uLogger.debug("CPU usages for parallel requests: [{}]".format(CPU_USAGES))
 594
 595        # this parameters insert to requests: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService
 596        # iType is type of instrument, it must be one of supported types in TKS_INSTRUMENTS list.
 597        iParams = [{"iType": iType} for iType in TKS_INSTRUMENTS]
 598
 599        poolUpdater = ThreadPool(processes=CPU_USAGES)  # create pool for update instruments in parallel mode
 600        listing = poolUpdater.map(self._IWrapper, iParams)  # execute update operations
 601        poolUpdater.close()
 602
 603        # Dictionary with all broker instruments: shares, currencies, bonds, etfs and futures.
 604        # Next in this code: item[0] is "iType" and item[1] is list of available instruments from the result of _IUpdater() method
 605        iList = {item[0]: {instrument["ticker"]: instrument for instrument in item[1]} for item in listing}
 606
 607        # calculate minimum price increment (step) for all instruments and set up instrument's type:
 608        for iType in iList.keys():
 609            for ticker in iList[iType]:
 610                iList[iType][ticker]["type"] = iType
 611
 612                if "minPriceIncrement" in iList[iType][ticker].keys():
 613                    iList[iType][ticker]["step"] = NanoToFloat(
 614                        iList[iType][ticker]["minPriceIncrement"]["units"],
 615                        iList[iType][ticker]["minPriceIncrement"]["nano"],
 616                    )
 617
 618                else:
 619                    iList[iType][ticker]["step"] = 0  # hack to avoid empty value in some instruments, e.g. futures
 620
 621        return iList
 622
 623    def DumpInstrumentsAsXLSX(self, forceUpdate: bool = False) -> None:
 624        """
 625        Creates XLSX-formatted dump file with raw data of instruments to further used by data scientists or stock analytics.
 626
 627        See also: `DumpInstruments()`, `Listing()`.
 628
 629        :param forceUpdate: if `True` then at first updates data with `Listing()` method,
 630                            otherwise just saves exist `iList` as XLSX-file (default: `dump.xlsx`) .
 631        """
 632        if self.iListDumpFile is None or not self.iListDumpFile:
 633            uLogger.error("Output name of dump file must be defined!")
 634            raise Exception("Filename required")
 635
 636        if not self.iList or forceUpdate:
 637            self.iList = self.Listing()
 638
 639        xlsxDumpFile = self.iListDumpFile.replace(".json", ".xlsx") if self.iListDumpFile.endswith(".json") else self.iListDumpFile + ".xlsx"
 640
 641        # Save as XLSX with separated sheets for every type of instruments:
 642        with pd.ExcelWriter(
 643                path=xlsxDumpFile,
 644                date_format=TKS_DATE_FORMAT,
 645                datetime_format=TKS_DATE_TIME_FORMAT,
 646                mode="w",
 647        ) as writer:
 648            for iType in TKS_INSTRUMENTS:
 649                df = pd.DataFrame.from_dict(data=self.iList[iType], orient="index")  # generate pandas object from self.iList dictionary
 650                df = df[sorted(df)]  # sorted by column names
 651                df = df.applymap(
 652                    lambda item: NanoToFloat(item["units"], item["nano"]) if isinstance(item, dict) and "units" in item.keys() and "nano" in item.keys() else item,
 653                    na_action="ignore",
 654                )  # converting numbers from nano-type to float in every cell
 655                df.to_excel(
 656                    writer,
 657                    sheet_name=iType,
 658                    encoding="UTF-8",
 659                    freeze_panes=(1, 1),
 660                )  # saving as XLSX-file with freeze first row and column as headers
 661
 662        uLogger.info("XLSX-file for further used by data scientists or stock analytics: [{}]".format(os.path.abspath(xlsxDumpFile)))
 663
 664    def DumpInstruments(self, forceUpdate: bool = True) -> str:
 665        """
 666        Receives and returns actual raw data about shares, currencies, bonds, etfs and futures from broker server
 667        using `Listing()` method. If `iListDumpFile` string is not empty then also save information to this file.
 668
 669        See also: `DumpInstrumentsAsXLSX()`, `Listing()`.
 670
 671        :param forceUpdate: if `True` then at first updates data with `Listing()` method,
 672                            otherwise just saves exist `iList` as JSON-file (default: `dump.json`).
 673        :return: serialized JSON formatted `str` with full data of instruments, also saved to the `--output` JSON-file.
 674        """
 675        if self.iListDumpFile is None or not self.iListDumpFile:
 676            uLogger.error("Output name of dump file must be defined!")
 677            raise Exception("Filename required")
 678
 679        if not self.iList or forceUpdate:
 680            self.iList = self.Listing()
 681
 682        jsonDump = json.dumps(self.iList, indent=4, sort_keys=False)  # create JSON object as string
 683        with open(self.iListDumpFile, mode="w", encoding="UTF-8") as fH:
 684            fH.write(jsonDump)
 685
 686        uLogger.info("New cache of instruments data was created: [{}]".format(os.path.abspath(self.iListDumpFile)))
 687
 688        return jsonDump
 689
 690    def ShowInstrumentInfo(self, iJSON: dict, show: bool = True) -> str:
 691        """
 692        Show information about one instrument defined by json data and prints it in Markdown format.
 693
 694        See also: `SearchByTicker()`, `SearchByFIGI()`, `RequestBondCoupons()`, `ExtendBondsData()`, `ShowBondsCalendar()` and `RequestTradingStatus()`.
 695
 696        :param iJSON: json data of instrument, example: `iJSON = self.iList["Shares"][self.ticker]`
 697        :param show: if `True` then also printing information about instrument and its current price.
 698        :return: multilines text in Markdown format with information about one instrument.
 699        """
 700        splitLine = "|                                                             |                                                        |\n"
 701        infoText = ""
 702
 703        if iJSON is not None and iJSON and isinstance(iJSON, dict):
 704            info = [
 705                "# Main information: ticker [{}], FIGI [{}]\n\n".format(iJSON["ticker"], iJSON["figi"]),
 706                "* Actual at: [{}] (UTC)\n\n".format(datetime.now(tzutc()).strftime("%Y-%m-%d %H:%M")),
 707                "| Parameters                                                  | Values                                                 |\n",
 708                "|-------------------------------------------------------------|--------------------------------------------------------|\n",
 709                "| Ticker:                                                     | {:<54} |\n".format(iJSON["ticker"]),
 710                "| Full name:                                                  | {:<54} |\n".format(iJSON["name"]),
 711            ]
 712
 713            if "sector" in iJSON.keys() and iJSON["sector"]:
 714                info.append("| Sector:                                                     | {:<54} |\n".format(iJSON["sector"]))
 715
 716            info.append("| Country of instrument:                                      | {:<54} |\n".format("{}{}".format(
 717                "({}) ".format(iJSON["countryOfRisk"]) if "countryOfRisk" in iJSON.keys() and iJSON["countryOfRisk"] else "",
 718                iJSON["countryOfRiskName"] if "countryOfRiskName" in iJSON.keys() and iJSON["countryOfRiskName"] else "",
 719            )))
 720
 721            info.extend([
 722                splitLine,
 723                "| FIGI (Financial Instrument Global Identifier):              | {:<54} |\n".format(iJSON["figi"]),
 724                "| Exchange:                                                   | {:<54} |\n".format(iJSON["exchange"]),
 725            ])
 726
 727            if "isin" in iJSON.keys() and iJSON["isin"]:
 728                info.append("| ISIN (International Securities Identification Number):      | {:<54} |\n".format(iJSON["isin"]))
 729
 730            if "classCode" in iJSON.keys():
 731                info.append("| Class Code (exchange section where instrument is traded):   | {:<54} |\n".format(iJSON["classCode"]))
 732
 733            info.extend([
 734                splitLine,
 735                "| Current broker security trading status:                     | {:<54} |\n".format(TKS_TRADING_STATUSES[iJSON["tradingStatus"]]),
 736                splitLine,
 737                "| Buy operations allowed:                                     | {:<54} |\n".format("Yes" if iJSON["buyAvailableFlag"] else "No"),
 738                "| Sale operations allowed:                                    | {:<54} |\n".format("Yes" if iJSON["sellAvailableFlag"] else "No"),
 739                "| Short positions allowed:                                    | {:<54} |\n".format("Yes" if iJSON["shortEnabledFlag"] else "No"),
 740            ])
 741
 742            if iJSON["figi"]:
 743                self.figi = iJSON["figi"]
 744                iJSON = iJSON | self.RequestTradingStatus()
 745
 746                info.extend([
 747                    splitLine,
 748                    "| Limit orders allowed:                                       | {:<54} |\n".format("Yes" if iJSON["limitOrderAvailableFlag"] else "No"),
 749                    "| Market orders allowed:                                      | {:<54} |\n".format("Yes" if iJSON["marketOrderAvailableFlag"] else "No"),
 750                    "| API trade allowed:                                          | {:<54} |\n".format("Yes" if iJSON["apiTradeAvailableFlag"] else "No"),
 751                ])
 752
 753            info.append(splitLine)
 754
 755            if "type" in iJSON.keys() and iJSON["type"]:
 756                info.append("| Type of the instrument:                                     | {:<54} |\n".format(iJSON["type"]))
 757
 758            if "futuresType" in iJSON.keys() and iJSON["futuresType"]:
 759                info.append("| Futures type:                                               | {:<54} |\n".format(iJSON["futuresType"]))
 760
 761            if "ipoDate" in iJSON.keys() and iJSON["ipoDate"]:
 762                info.append("| IPO date:                                                   | {:<54} |\n".format(iJSON["ipoDate"].replace("T", " ").replace("Z", "")))
 763
 764            if "releasedDate" in iJSON.keys() and iJSON["releasedDate"]:
 765                info.append("| Released date:                                              | {:<54} |\n".format(iJSON["releasedDate"].replace("T", " ").replace("Z", "")))
 766
 767            if "rebalancingFreq" in iJSON.keys() and iJSON["rebalancingFreq"]:
 768                info.append("| Rebalancing frequency:                                      | {:<54} |\n".format(iJSON["rebalancingFreq"]))
 769
 770            if "focusType" in iJSON.keys() and iJSON["focusType"]:
 771                info.append("| Focusing type:                                              | {:<54} |\n".format(iJSON["focusType"]))
 772
 773            if "assetType" in iJSON.keys() and iJSON["assetType"]:
 774                info.append("| Asset type:                                                 | {:<54} |\n".format(iJSON["assetType"]))
 775
 776            if "basicAsset" in iJSON.keys() and iJSON["basicAsset"]:
 777                info.append("| Basic asset:                                                | {:<54} |\n".format(iJSON["basicAsset"]))
 778
 779            if "basicAssetSize" in iJSON.keys() and iJSON["basicAssetSize"]:
 780                info.append("| Basic asset size:                                           | {:<54} |\n".format("{:.2f}".format(NanoToFloat(str(iJSON["basicAssetSize"]["units"]), iJSON["basicAssetSize"]["nano"]))))
 781
 782            if "isoCurrencyName" in iJSON.keys() and iJSON["isoCurrencyName"]:
 783                info.append("| ISO currency name:                                          | {:<54} |\n".format(iJSON["isoCurrencyName"]))
 784
 785            if "currency" in iJSON.keys():
 786                info.append("| Payment currency:                                           | {:<54} |\n".format(iJSON["currency"]))
 787
 788            if iJSON["type"] == "Bonds" and "nominal" in iJSON.keys() and "currency" in iJSON["nominal"].keys():
 789                info.append("| Nominal currency:                                           | {:<54} |\n".format(iJSON["nominal"]["currency"]))
 790
 791            if "firstTradeDate" in iJSON.keys() and iJSON["firstTradeDate"]:
 792                info.append("| First trade date:                                           | {:<54} |\n".format(iJSON["firstTradeDate"].replace("T", " ").replace("Z", "")))
 793
 794            if "lastTradeDate" in iJSON.keys() and iJSON["lastTradeDate"]:
 795                info.append("| Last trade date:                                            | {:<54} |\n".format(iJSON["lastTradeDate"].replace("T", " ").replace("Z", "")))
 796
 797            if "expirationDate" in iJSON.keys() and iJSON["expirationDate"]:
 798                info.append("| Date of expiration:                                         | {:<54} |\n".format(iJSON["expirationDate"].replace("T", " ").replace("Z", "")))
 799
 800            if "stateRegDate" in iJSON.keys() and iJSON["stateRegDate"]:
 801                info.append("| State registration date:                                    | {:<54} |\n".format(iJSON["stateRegDate"].replace("T", " ").replace("Z", "")))
 802
 803            if "placementDate" in iJSON.keys() and iJSON["placementDate"]:
 804                info.append("| Placement date:                                             | {:<54} |\n".format(iJSON["placementDate"].replace("T", " ").replace("Z", "")))
 805
 806            if "maturityDate" in iJSON.keys() and iJSON["maturityDate"]:
 807                info.append("| Maturity date:                                              | {:<54} |\n".format(iJSON["maturityDate"].replace("T", " ").replace("Z", "")))
 808
 809            if "perpetualFlag" in iJSON.keys() and iJSON["perpetualFlag"]:
 810                info.append("| Perpetual bond:                                             | Yes                                                    |\n")
 811
 812            if "otcFlag" in iJSON.keys() and iJSON["otcFlag"]:
 813                info.append("| Over-the-counter (OTC) securities:                          | Yes                                                    |\n")
 814
 815            iExt = None
 816            if iJSON["type"] == "Bonds":
 817                info.extend([
 818                    splitLine,
 819                    "| Bond issue (size / plan):                                   | {:<54} |\n".format("{} / {}".format(iJSON["issueSize"], iJSON["issueSizePlan"])),
 820                    "| Nominal price (100%):                                       | {:<54} |\n".format("{} {}".format(
 821                        "{:.2f}".format(NanoToFloat(str(iJSON["nominal"]["units"]), iJSON["nominal"]["nano"])).rstrip("0").rstrip("."),
 822                        iJSON["nominal"]["currency"],
 823                    )),
 824                ])
 825
 826                if "floatingCouponFlag" in iJSON.keys():
 827                    info.append("| Floating coupon:                                            | {:<54} |\n".format("Yes" if iJSON["floatingCouponFlag"] else "No"))
 828
 829                if "amortizationFlag" in iJSON.keys():
 830                    info.append("| Amortization:                                               | {:<54} |\n".format("Yes" if iJSON["amortizationFlag"] else "No"))
 831
 832                info.append(splitLine)
 833
 834                if "couponQuantityPerYear" in iJSON.keys() and iJSON["couponQuantityPerYear"]:
 835                    info.append("| Number of coupon payments per year:                         | {:<54} |\n".format(iJSON["couponQuantityPerYear"]))
 836
 837                if iJSON["figi"]:
 838                    iExt = self.ExtendBondsData(instruments=iJSON["figi"], xlsx=False)  # extended bonds data
 839
 840                    info.extend([
 841                        "| Days last to maturity date:                                 | {:<54} |\n".format(iExt["daysToMaturity"][0]),
 842                        "| Coupons yield (average coupon daily yield * 365):           | {:<54} |\n".format("{:.2f}%".format(iExt["couponsYield"][0])),
 843                        "| Current price yield (average daily yield * 365):            | {:<54} |\n".format("{:.2f}%".format(iExt["currentYield"][0])),
 844                    ])
 845
 846                if "aciValue" in iJSON.keys() and iJSON["aciValue"]:
 847                    info.append("| Current accumulated coupon income (ACI):                    | {:<54} |\n".format("{:.2f} {}".format(
 848                        NanoToFloat(str(iJSON["aciValue"]["units"]), iJSON["aciValue"]["nano"]),
 849                        iJSON["aciValue"]["currency"]
 850                    )))
 851
 852            if "currentPrice" in iJSON.keys():
 853                info.append(splitLine)
 854
 855                currency = iJSON["currency"] if "currency" in iJSON.keys() else ""  # nominal currency for bonds, otherwise currency of instrument
 856                aciCurrency = iExt["aciCurrency"][0] if iJSON["type"] == "Bonds" and iExt is not None and "aciCurrency" in iExt.keys() else ""  # payment currency
 857
 858                bondPrevClose = iExt["closePrice"][0] if iJSON["type"] == "Bonds" and iExt is not None and "closePrice" in iExt.keys() else 0  # previous close price of bond
 859                bondLastPrice = iExt["lastPrice"][0] if iJSON["type"] == "Bonds" and iExt is not None and "lastPrice" in iExt.keys() else 0  # last price of bond
 860                bondLimitUp = iExt["limitUp"][0] if iJSON["type"] == "Bonds" and iExt is not None and "limitUp" in iExt.keys() else 0  # max price of bond
 861                bondLimitDown = iExt["limitDown"][0] if iJSON["type"] == "Bonds" and iExt is not None and "limitDown" in iExt.keys() else 0  # min price of bond
 862                bondChangesDelta = iExt["changesDelta"][0] if iJSON["type"] == "Bonds" and iExt is not None and "changesDelta" in iExt.keys() else 0  # delta between last deal price and last close
 863
 864                curPriceSell = iJSON["currentPrice"]["sell"][0]["price"] if iJSON["currentPrice"]["sell"] else 0
 865                curPriceBuy = iJSON["currentPrice"]["buy"][0]["price"] if iJSON["currentPrice"]["buy"] else 0
 866
 867                info.extend([
 868                    "| Previous close price of the instrument:                     | {:<54} |\n".format("{}{}".format(
 869                        "{}".format(iJSON["currentPrice"]["closePrice"]).rstrip("0").rstrip(".") if iJSON["currentPrice"]["closePrice"] is not None else "N/A",
 870                        "% of nominal price ({:.2f} {})".format(bondPrevClose, aciCurrency) if iJSON["type"] == "Bonds" else " {}".format(currency),
 871                    )),
 872                    "| Last deal price of the instrument:                          | {:<54} |\n".format("{}{}".format(
 873                        "{}".format(iJSON["currentPrice"]["lastPrice"]).rstrip("0").rstrip(".") if iJSON["currentPrice"]["lastPrice"] is not None else "N/A",
 874                        "% of nominal price ({:.2f} {})".format(bondLastPrice, aciCurrency) if iJSON["type"] == "Bonds" else " {}".format(currency),
 875                    )),
 876                    "| Changes between last deal price and last close              | {:<54} |\n".format(
 877                        "{:.2f}%{}".format(
 878                            iJSON["currentPrice"]["changes"],
 879                            " ({}{:.2f} {})".format(
 880                                "+" if bondChangesDelta > 0 else "",
 881                                bondChangesDelta,
 882                                aciCurrency
 883                            ) if iJSON["type"] == "Bonds" else " ({}{:.2f} {})".format(
 884                                "+" if iJSON["currentPrice"]["lastPrice"] > iJSON["currentPrice"]["closePrice"] else "",
 885                                iJSON["currentPrice"]["lastPrice"] - iJSON["currentPrice"]["closePrice"],
 886                                currency
 887                            ),
 888                        )
 889                    ),
 890                    "| Current limit price, min / max:                             | {:<54} |\n".format("{}{} / {}{}{}".format(
 891                        "{}".format(iJSON["currentPrice"]["limitDown"]).rstrip("0").rstrip(".") if iJSON["currentPrice"]["limitDown"] is not None else "N/A",
 892                        "%" if iJSON["type"] == "Bonds" else " {}".format(currency),
 893                        "{}".format(iJSON["currentPrice"]["limitUp"]).rstrip("0").rstrip(".") if iJSON["currentPrice"]["limitUp"] is not None else "N/A",
 894                        "%" if iJSON["type"] == "Bonds" else " {}".format(currency),
 895                        " ({:.2f} {} / {:.2f} {})".format(bondLimitDown, aciCurrency, bondLimitUp, aciCurrency) if iJSON["type"] == "Bonds" else ""
 896                    )),
 897                    "| Actual price, sell / buy:                                   | {:<54} |\n".format("{}{} / {}{}{}".format(
 898                        "{}".format(curPriceSell).rstrip("0").rstrip(".") if curPriceSell != 0 else "N/A",
 899                        "%" if iJSON["type"] == "Bonds" else " {}".format(currency),
 900                        "{}".format(curPriceBuy).rstrip("0").rstrip(".") if curPriceBuy != 0 else "N/A",
 901                        "%" if iJSON["type"] == "Bonds" else" {}".format(currency),
 902                        " ({:.2f} {} / {:.2f} {})".format(curPriceSell, aciCurrency, curPriceBuy, aciCurrency) if iJSON["type"] == "Bonds" else ""
 903                    )),
 904                ])
 905
 906            if "lot" in iJSON.keys():
 907                info.append("| Minimum lot to buy:                                         | {:<54} |\n".format(iJSON["lot"]))
 908
 909            if "step" in iJSON.keys() and iJSON["step"] != 0:
 910                info.append("| Minimum price increment (step):                             | {:<54} |\n".format(iJSON["step"]))
 911
 912            # Add bond payment calendar:
 913            if iJSON["type"] == "Bonds":
 914                strCalendar = self.ShowBondsCalendar(extBonds=iExt, show=False)   # bond payment calendar
 915                info.extend(["\n", strCalendar])
 916
 917            infoText += "".join(info)
 918
 919            if show:
 920                uLogger.info("{}".format(infoText))
 921
 922            else:
 923                uLogger.debug("{}".format(infoText))
 924
 925            if self.infoFile is not None:
 926                with open(self.infoFile, "w", encoding="UTF-8") as fH:
 927                    fH.write(infoText)
 928
 929                uLogger.info("Info about instrument with ticker [{}] and FIGI [{}] was saved to file: [{}]".format(iJSON["ticker"], iJSON["figi"], os.path.abspath(self.infoFile)))
 930
 931        return infoText
 932
 933    def SearchByTicker(self, requestPrice: bool = False, show: bool = False) -> dict:
 934        """
 935        Search and return raw broker's information about instrument by its ticker. Variable `ticker` must be defined!
 936
 937        :param requestPrice: if `False` then do not request current price of instrument (because this is long operation).
 938        :param show: if `False` then do not run `ShowInstrumentInfo()` method and do not print info to the console.
 939        :return: JSON formatted data with information about instrument.
 940        """
 941        tickerJSON = {}
 942        if self.moreDebug:
 943            uLogger.debug("Searching information about instrument by it's ticker [{}] ...".format(self.ticker))
 944
 945        if not self.ticker:
 946            uLogger.warning("self.ticker variable is not be empty!")
 947
 948        else:
 949            if self.ticker in TKS_TICKERS_OR_FIGI_EXCLUDED:
 950                uLogger.warning("Instrument with ticker [{}] not allowed for trading!".format(self.ticker))
 951                raise Exception("Instrument not allowed")
 952
 953            if not self.iList:
 954                self.iList = self.Listing()
 955
 956            if self.ticker in self.iList["Shares"].keys():
 957                tickerJSON = self.iList["Shares"][self.ticker]
 958                if self.moreDebug:
 959                    uLogger.debug("Ticker [{}] found in shares list".format(self.ticker))
 960
 961            elif self.ticker in self.iList["Currencies"].keys():
 962                tickerJSON = self.iList["Currencies"][self.ticker]
 963                if self.moreDebug:
 964                    uLogger.debug("Ticker [{}] found in currencies list".format(self.ticker))
 965
 966            elif self.ticker in self.iList["Bonds"].keys():
 967                tickerJSON = self.iList["Bonds"][self.ticker]
 968                if self.moreDebug:
 969                    uLogger.debug("Ticker [{}] found in bonds list".format(self.ticker))
 970
 971            elif self.ticker in self.iList["Etfs"].keys():
 972                tickerJSON = self.iList["Etfs"][self.ticker]
 973                if self.moreDebug:
 974                    uLogger.debug("Ticker [{}] found in etfs list".format(self.ticker))
 975
 976            elif self.ticker in self.iList["Futures"].keys():
 977                tickerJSON = self.iList["Futures"][self.ticker]
 978                if self.moreDebug:
 979                    uLogger.debug("Ticker [{}] found in futures list".format(self.ticker))
 980
 981        if tickerJSON:
 982            self.figi = tickerJSON["figi"]
 983
 984            if requestPrice:
 985                tickerJSON["currentPrice"] = self.GetCurrentPrices(show=False)
 986
 987                if tickerJSON["currentPrice"]["closePrice"] is not None and tickerJSON["currentPrice"]["closePrice"] != 0 and tickerJSON["currentPrice"]["lastPrice"] is not None:
 988                    tickerJSON["currentPrice"]["changes"] = 100 * (tickerJSON["currentPrice"]["lastPrice"] - tickerJSON["currentPrice"]["closePrice"]) / tickerJSON["currentPrice"]["closePrice"]
 989
 990                else:
 991                    tickerJSON["currentPrice"]["changes"] = 0
 992
 993            if show:
 994                self.ShowInstrumentInfo(iJSON=tickerJSON, show=True)  # print info as Markdown text
 995
 996        else:
 997            if show:
 998                uLogger.warning("Ticker [{}] not found in available broker instrument's list!".format(self.ticker))
 999
1000        return tickerJSON
1001
1002    def SearchByFIGI(self, requestPrice: bool = False, show: bool = False) -> dict:
1003        """
1004        Search and return raw broker's information about instrument by its FIGI. Variable `figi` must be defined!
1005
1006        :param requestPrice: if `False` then do not request current price of instrument (it's long operation).
1007        :param show: if `False` then do not run `ShowInstrumentInfo()` method and do not print info to the console.
1008        :return: JSON formatted data with information about instrument.
1009        """
1010        figiJSON = {}
1011        if self.moreDebug:
1012            uLogger.debug("Searching information about instrument by it's FIGI [{}] ...".format(self.figi))
1013
1014        if not self.figi:
1015            uLogger.warning("self.figi variable is not be empty!")
1016
1017        else:
1018            if self.figi in TKS_TICKERS_OR_FIGI_EXCLUDED:
1019                uLogger.warning("Instrument with figi [{}] not allowed for trading!".format(self.figi))
1020                raise Exception("Instrument not allowed")
1021
1022            if not self.iList:
1023                self.iList = self.Listing()
1024
1025            for item in self.iList["Shares"].keys():
1026                if self.figi == self.iList["Shares"][item]["figi"]:
1027                    figiJSON = self.iList["Shares"][item]
1028
1029                    if self.moreDebug:
1030                        uLogger.debug("FIGI [{}] found in shares list".format(self.figi))
1031
1032                    break
1033
1034            if not figiJSON:
1035                for item in self.iList["Currencies"].keys():
1036                    if self.figi == self.iList["Currencies"][item]["figi"]:
1037                        figiJSON = self.iList["Currencies"][item]
1038
1039                        if self.moreDebug:
1040                            uLogger.debug("FIGI [{}] found in currencies list".format(self.figi))
1041
1042                        break
1043
1044            if not figiJSON:
1045                for item in self.iList["Bonds"].keys():
1046                    if self.figi == self.iList["Bonds"][item]["figi"]:
1047                        figiJSON = self.iList["Bonds"][item]
1048
1049                        if self.moreDebug:
1050                            uLogger.debug("FIGI [{}] found in bonds list".format(self.figi))
1051
1052                        break
1053
1054            if not figiJSON:
1055                for item in self.iList["Etfs"].keys():
1056                    if self.figi == self.iList["Etfs"][item]["figi"]:
1057                        figiJSON = self.iList["Etfs"][item]
1058
1059                        if self.moreDebug:
1060                            uLogger.debug("FIGI [{}] found in etfs list".format(self.figi))
1061
1062                        break
1063
1064            if not figiJSON:
1065                for item in self.iList["Futures"].keys():
1066                    if self.figi == self.iList["Futures"][item]["figi"]:
1067                        figiJSON = self.iList["Futures"][item]
1068
1069                        if self.moreDebug:
1070                            uLogger.debug("FIGI [{}] found in futures list".format(self.figi))
1071
1072                        break
1073
1074        if figiJSON:
1075            self.figi = figiJSON["figi"]
1076            self.ticker = figiJSON["ticker"]
1077
1078            if requestPrice:
1079                figiJSON["currentPrice"] = self.GetCurrentPrices(show=False)
1080
1081                if figiJSON["currentPrice"]["closePrice"] is not None and figiJSON["currentPrice"]["closePrice"] != 0 and figiJSON["currentPrice"]["lastPrice"] is not None:
1082                    figiJSON["currentPrice"]["changes"] = 100 * (figiJSON["currentPrice"]["lastPrice"] - figiJSON["currentPrice"]["closePrice"]) / figiJSON["currentPrice"]["closePrice"]
1083
1084                else:
1085                    figiJSON["currentPrice"]["changes"] = 0
1086
1087            if show:
1088                self.ShowInstrumentInfo(iJSON=figiJSON, show=True)  # print info as Markdown text
1089
1090        else:
1091            if show:
1092                uLogger.warning("FIGI [{}] not found in available broker instrument's list!".format(self.figi))
1093
1094        return figiJSON
1095
1096    def GetCurrentPrices(self, show: bool = True) -> dict:
1097        """
1098        Get and show Depth of Market with current prices of the instrument as dictionary. Result example with `depth` 5:
1099        `{"buy": [{"price": 1243.8, "quantity": 193},
1100                  {"price": 1244.0, "quantity": 168},
1101                  {"price": 1244.8, "quantity": 5},
1102                  {"price": 1245.0, "quantity": 61},
1103                  {"price": 1245.4, "quantity": 60}],
1104          "sell": [{"price": 1243.6, "quantity": 8},
1105                   {"price": 1242.6, "quantity": 10},
1106                   {"price": 1242.4, "quantity": 18},
1107                   {"price": 1242.2, "quantity": 50},
1108                   {"price": 1242.0, "quantity": 113}],
1109          "limitUp": 1619.0, "limitDown": 903.4, "lastPrice": 1243.8, "closePrice": 1263.0}`, where parameters mean:
1110        - buy: list of dicts with Sellers prices, see also: https://tinkoff.github.io/investAPI/marketdata/#order
1111        - sell: list of dicts with Buyers prices,
1112            - price: price of 1 instrument (to get the cost of the lot, you need to multiply it by the lot of size of the instrument),
1113            - quantity: volume value by current price in lots,
1114        - limitUp: current trade session limit price, maximum,
1115        - limitDown: current trade session limit price, minimum,
1116        - lastPrice: last deal price of the instrument,
1117        - closePrice: previous trade session close price of the instrument.
1118
1119        See also: `SearchByTicker()` and `SearchByFIGI()`.
1120        REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/MarketDataService/MarketDataService_GetOrderBook
1121        Response fields: https://tinkoff.github.io/investAPI/marketdata/#getorderbookresponse
1122
1123        :param show: if `True` then print DOM to log and console.
1124        :return: orders book dict with lists of current buy and sell prices: `{"buy": [{"price": x1, "quantity": y1, ...}], "sell": [....]}`.
1125                 If an error occurred then returns an empty record:
1126                 `{"buy": [], "sell": [], "limitUp": None, "limitDown": None, "lastPrice": None, "closePrice": None}`.
1127        """
1128        prices = {"buy": [], "sell": [], "limitUp": 0, "limitDown": 0, "lastPrice": 0, "closePrice": 0}
1129
1130        if self.depth < 1:
1131            uLogger.error("Depth of Market (DOM) must be >=1!")
1132            raise Exception("Incorrect value")
1133
1134        if not (self.ticker or self.figi):
1135            uLogger.error("self.ticker or self.figi variables must be defined!")
1136            raise Exception("Ticker or FIGI required")
1137
1138        if self.ticker and not self.figi:
1139            instrumentByTicker = self.SearchByTicker(requestPrice=False)  # WARNING! requestPrice=False to avoid recursion!
1140            self.figi = instrumentByTicker["figi"] if instrumentByTicker else ""
1141
1142        if not self.ticker and self.figi:
1143            instrumentByFigi = self.SearchByFIGI(requestPrice=False)  # WARNING! requestPrice=False to avoid recursion!
1144            self.ticker = instrumentByFigi["ticker"] if instrumentByFigi else ""
1145
1146        if not self.figi:
1147            uLogger.error("FIGI is not defined!")
1148            raise Exception("Ticker or FIGI required")
1149
1150        else:
1151            uLogger.debug("Requesting current prices: ticker [{}], FIGI [{}]. Wait, please...".format(self.ticker, self.figi))
1152
1153            # REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/MarketDataService/MarketDataService_GetOrderBook
1154            priceURL = self.server + r"/tinkoff.public.invest.api.contract.v1.MarketDataService/GetOrderBook"
1155            self.body = str({"figi": self.figi, "depth": self.depth})
1156            pricesResponse = self.SendAPIRequest(priceURL, reqType="POST")  # Response fields: https://tinkoff.github.io/investAPI/marketdata/#getorderbookresponse
1157
1158            if pricesResponse and not ("code" in pricesResponse.keys() or "message" in pricesResponse.keys() or "description" in pricesResponse.keys()):
1159                # list of dicts with sellers orders:
1160                prices["buy"] = [{"price": round(NanoToFloat(item["price"]["units"], item["price"]["nano"]), 6), "quantity": int(item["quantity"])} for item in pricesResponse["asks"]]
1161
1162                # list of dicts with buyers orders:
1163                prices["sell"] = [{"price": round(NanoToFloat(item["price"]["units"], item["price"]["nano"]), 6), "quantity": int(item["quantity"])} for item in pricesResponse["bids"]]
1164
1165                # max price of instrument at this time:
1166                prices["limitUp"] = round(NanoToFloat(pricesResponse["limitUp"]["units"], pricesResponse["limitUp"]["nano"]), 6) if "limitUp" in pricesResponse.keys() else None
1167
1168                # min price of instrument at this time:
1169                prices["limitDown"] = round(NanoToFloat(pricesResponse["limitDown"]["units"], pricesResponse["limitDown"]["nano"]), 6) if "limitDown" in pricesResponse.keys() else None
1170
1171                # last price of deal with instrument:
1172                prices["lastPrice"] = round(NanoToFloat(pricesResponse["lastPrice"]["units"], pricesResponse["lastPrice"]["nano"]), 6) if "lastPrice" in pricesResponse.keys() else 0
1173
1174                # last close price of instrument:
1175                prices["closePrice"] = round(NanoToFloat(pricesResponse["closePrice"]["units"], pricesResponse["closePrice"]["nano"]), 6) if "closePrice" in pricesResponse.keys() else 0
1176
1177            else:
1178                uLogger.warning("Server return an empty or error response! See full log. Instrument: ticker [{}], FIGI [{}]".format(self.ticker, self.figi))
1179                uLogger.debug("Server response: {}".format(pricesResponse))
1180
1181            if show:
1182                if prices["buy"] or prices["sell"]:
1183                    info = [
1184                        "Orders book actual at [{}] (UTC)\nTicker: [{}], FIGI: [{}], Depth of Market: [{}]\n".format(
1185                            datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT),
1186                            self.ticker,
1187                            self.figi,
1188                            self.depth,
1189                        ),
1190                        "-" * 60, "\n",
1191                        "             Orders of Buyers | Orders of Sellers\n",
1192                        "-" * 60, "\n",
1193                        "        Sell prices (volumes) | Buy prices (volumes)\n",
1194                        "-" * 60, "\n",
1195                    ]
1196
1197                    if not prices["buy"]:
1198                        info.append("                              | No orders!\n")
1199                        sumBuy = 0
1200
1201                    else:
1202                        sumBuy = sum([x["quantity"] for x in prices["buy"]])
1203                        maxMinSorted = sorted(prices["buy"], key=lambda k: k["price"], reverse=True)
1204                        for item in maxMinSorted:
1205                            info.append("                              | {} ({})\n".format(item["price"], item["quantity"]))
1206
1207                    if not prices["sell"]:
1208                        info.append("No orders!                    |\n")
1209                        sumSell = 0
1210
1211                    else:
1212                        sumSell = sum([x["quantity"] for x in prices["sell"]])
1213                        for item in prices["sell"]:
1214                            info.append("{:>29} |\n".format("{} ({})".format(item["price"], item["quantity"])))
1215
1216                    info.extend([
1217                        "-" * 60, "\n",
1218                        "{:>29} | {}\n".format("Total sell: {}".format(sumSell), "Total buy: {}".format(sumBuy)),
1219                        "-" * 60, "\n",
1220                    ])
1221
1222                    infoText = "".join(info)
1223
1224                    uLogger.info("Current prices in order book:\n\n{}".format(infoText))
1225
1226                else:
1227                    uLogger.warning("Orders book is empty at this time! Instrument: ticker [{}], FIGI [{}]".format(self.ticker, self.figi))
1228
1229        return prices
1230
1231    def ShowInstrumentsInfo(self, show: bool = True) -> str:
1232        """
1233        This method get and show information about all available broker instruments for current user account.
1234        If `instrumentsFile` string is not empty then also save information to this file.
1235
1236        :param show: if `True` then print results to console, if `False` - print only to file.
1237        :return: multi-lines string with all available broker instruments
1238        """
1239        if not self.iList:
1240            self.iList = self.Listing()
1241
1242        info = [
1243            "# All available instruments from Tinkoff Broker server for current user token\n\n",
1244            "* **Actual on date:** [{} UTC]\n".format(datetime.now(tzutc()).strftime("%Y-%m-%d %H:%M")),
1245        ]
1246
1247        # add instruments count by type:
1248        for iType in self.iList.keys():
1249            info.append("* **{}:** [{}]\n".format(iType, len(self.iList[iType])))
1250
1251        headerLine = "| Ticker       | Full name                                                 | FIGI         | Cur | Lot     | Step       |\n"
1252        splitLine = "|--------------|-----------------------------------------------------------|--------------|-----|---------|------------|\n"
1253
1254        # generating info tables with all instruments by type:
1255        for iType in self.iList.keys():
1256            info.extend(["\n\n## {} available. Total: [{}]\n\n".format(iType, len(self.iList[iType])), headerLine, splitLine])
1257
1258            for instrument in self.iList[iType].keys():
1259                iName = self.iList[iType][instrument]["name"]  # instrument's name
1260                if len(iName) > 57:
1261                    iName = "{}...".format(iName[:54])  # right trim for a long string
1262
1263                info.append("| {:<12} | {:<57} | {:<12} | {:<3} | {:<7} | {:<10} |\n".format(
1264                    self.iList[iType][instrument]["ticker"],
1265                    iName,
1266                    self.iList[iType][instrument]["figi"],
1267                    self.iList[iType][instrument]["currency"],
1268                    self.iList[iType][instrument]["lot"],
1269                    "{:.10f}".format(self.iList[iType][instrument]["step"]).rstrip("0").rstrip(".") if self.iList[iType][instrument]["step"] > 0 else 0,
1270                ))
1271
1272        infoText = "".join(info)
1273
1274        if show:
1275            uLogger.info(infoText)
1276
1277        if self.instrumentsFile:
1278            with open(self.instrumentsFile, "w", encoding="UTF-8") as fH:
1279                fH.write(infoText)
1280
1281            uLogger.info("All available instruments are saved to file: [{}]".format(os.path.abspath(self.instrumentsFile)))
1282
1283        return infoText
1284
1285    def SearchInstruments(self, pattern: str, show: bool = True) -> dict:
1286        """
1287        This method search and show information about instruments by part of its ticker, FIGI or name.
1288        If `searchResultsFile` string is not empty then also save information to this file.
1289
1290        :param pattern: string with part of ticker, FIGI or instrument's name.
1291        :param show: if `True` then print results to console, if `False` - return list of result only.
1292        :return: list of dictionaries with all found instruments.
1293        """
1294        if not self.iList:
1295            self.iList = self.Listing()
1296
1297        searchResults = {iType: {} for iType in self.iList}  # same as iList but will contains only filtered instruments
1298        compiledPattern = re.compile(pattern, re.IGNORECASE)
1299
1300        for iType in self.iList:
1301            for instrument in self.iList[iType].values():
1302                searchResult = compiledPattern.search(" ".join(
1303                    [instrument["ticker"], instrument["figi"], instrument["name"]]
1304                ))
1305
1306                if searchResult:
1307                    searchResults[iType][instrument["ticker"]] = instrument
1308
1309        resultsLen = sum([len(searchResults[iType]) for iType in searchResults])
1310        info = [
1311            "# Search results\n\n",
1312            "* **Search pattern:** [{}]\n".format(pattern),
1313            "* **Found instruments:** [{}]\n\n".format(resultsLen),
1314            "**Note:** you can view info about found instruments with key `--info`, e.g.: `tksbrokerapi -t TICKER --info` or `tksbrokerapi -f FIGI --info`.\n"
1315        ]
1316        infoShort = info[:]
1317
1318        headerLine = "| Type       | Ticker       | Full name                                                      | FIGI         |\n"
1319        splitLine = "|------------|--------------|----------------------------------------------------------------|--------------|\n"
1320        skippedLine = "| ...        | ...          | ...                                                            | ...          |\n"
1321
1322        if resultsLen == 0:
1323            info.append("\nNo results\n")
1324            infoShort.append("\nNo results\n")
1325            uLogger.warning("No results. Try changing your search pattern.")
1326
1327        else:
1328            for iType in searchResults:
1329                iTypeValuesCount = len(searchResults[iType].values())
1330                if iTypeValuesCount > 0:
1331                    info.extend(["\n### {}: [{}]\n\n".format(iType, iTypeValuesCount), headerLine, splitLine])
1332                    infoShort.extend(["\n### {}: [{}]\n\n".format(iType, iTypeValuesCount), headerLine, splitLine])
1333
1334                    for instrument in searchResults[iType].values():
1335                        info.append("| {:<10} | {:<12} | {:<63}| {:<13}|\n".format(
1336                            instrument["type"],
1337                            instrument["ticker"],
1338                            "{}...".format(instrument["name"][:60]) if len(instrument["name"]) > 63 else instrument["name"],  # right trim for a long string
1339                            instrument["figi"],
1340                        ))
1341
1342                    if iTypeValuesCount <= 5:
1343                        infoShort.extend(info[-iTypeValuesCount:])
1344
1345                    else:
1346                        infoShort.extend(info[-5:])
1347                        infoShort.append(skippedLine)
1348
1349        infoText = "".join(info)
1350        infoTextShort = "".join(infoShort)
1351
1352        if show:
1353            uLogger.info(infoTextShort)
1354            uLogger.info("You can view info about found instruments with key `--info`, e.g.: `tksbrokerapi -t IBM --info` or `tksbrokerapi -f BBG000BLNNH6 --info`")
1355
1356        if self.searchResultsFile:
1357            with open(self.searchResultsFile, "w", encoding="UTF-8") as fH:
1358                fH.write(infoText)
1359
1360            uLogger.info("Full search results were saved to file: [{}]".format(os.path.abspath(self.searchResultsFile)))
1361
1362        return searchResults
1363
1364    def GetUniqueFIGIs(self, instruments: list[str]) -> list:
1365        """
1366        Creating list with unique instrument FIGIs from input list of tickers or FIGIs.
1367
1368        :param instruments: list of strings with tickers or FIGIs.
1369        :return: list with unique instrument FIGIs only.
1370        """
1371        requestedInstruments = []
1372        for iName in instruments:
1373            if iName not in self.aliases.keys():
1374                if iName not in requestedInstruments:
1375                    requestedInstruments.append(iName)
1376
1377            else:
1378                if iName not in requestedInstruments:
1379                    if self.aliases[iName] not in requestedInstruments:
1380                        requestedInstruments.append(self.aliases[iName])
1381
1382        uLogger.debug("Requested instruments without duplicates of tickers or FIGIs: {}".format(requestedInstruments))
1383
1384        onlyUniqueFIGIs = []
1385        for iName in requestedInstruments:
1386            if iName in TKS_TICKERS_OR_FIGI_EXCLUDED:
1387                continue
1388
1389            self.ticker = iName
1390            iData = self.SearchByTicker(requestPrice=False)  # trying to find instrument by ticker
1391
1392            if not iData:
1393                self.ticker = ""
1394                self.figi = iName
1395
1396                iData = self.SearchByFIGI(requestPrice=False)  # trying to find instrument by FIGI
1397
1398                if not iData:
1399                    self.figi = ""
1400                    uLogger.warning("Instrument [{}] not in list of available instruments for current token!".format(iName))
1401
1402            if iData and iData["figi"] not in onlyUniqueFIGIs:
1403                onlyUniqueFIGIs.append(iData["figi"])
1404
1405        uLogger.debug("Unique list of FIGIs: {}".format(onlyUniqueFIGIs))
1406
1407        return onlyUniqueFIGIs
1408
1409    def GetListOfPrices(self, instruments: list, show: bool = False) -> list:
1410        """
1411        This method get, maybe show and return prices of list of instruments. WARNING! This is potential long operation!
1412        See limits: https://tinkoff.github.io/investAPI/limits/
1413        If `pricesFile` string is not empty then also save information to this file.
1414
1415        :param instruments: list of strings with tickers or FIGIs.
1416        :param show: if `True` then prints prices to console, if `False` - prints only to file `pricesFile`.
1417        :return: list of instruments looks like `[{some ticker info, "currentPrice": {current prices}}, {...}, ...]`.
1418                 One item is dict returned by `SearchByTicker()` or `SearchByFIGI()` methods.
1419        """
1420        if instruments is None or not instruments:
1421            uLogger.error("You must define some of tickers or FIGIs to request it's actual prices!")
1422            raise Exception("Ticker or FIGI required")
1423
1424        onlyUniqueFIGIs = self.GetUniqueFIGIs(instruments)
1425
1426        uLogger.debug("Requesting current prices from Tinkoff Broker server...")
1427
1428        iList = []  # trying to get info and current prices about all unique instruments:
1429        for self.figi in onlyUniqueFIGIs:
1430            iData = self.SearchByFIGI(requestPrice=True)
1431            iList.append(iData)
1432
1433        self.ShowListOfPrices(iList, show)
1434
1435        return iList
1436
1437    def ShowListOfPrices(self, iList: list, show: bool = True) -> str:
1438        """
1439        Show table contains current prices of given instruments.
1440
1441        :param iList: list of instruments looks like `[{some ticker info, "currentPrice": {current prices}}, {...}, ...]`.
1442                      One item is dict returned by `SearchByTicker(requestPrice=True)` or by `SearchByFIGI(requestPrice=True)` methods.
1443        :param show: if `True` then prints prices to console, if `False` - prints only to file `pricesFile`.
1444        :return: multilines text in Markdown format as a table contains current prices.
1445        """
1446        infoText = ""
1447
1448        if show or self.pricesFile:
1449            info = [
1450                "# Actual prices at: [{} UTC]\n\n".format(datetime.now(tzutc()).strftime("%Y-%m-%d %H:%M")),
1451                "| Ticker       | FIGI         | Type       | Prev. close | Last price  | Chg. %   | Day limits min/max  | Actual sell / buy   | Curr. |\n",
1452                "|--------------|--------------|------------|-------------|-------------|----------|---------------------|---------------------|-------|\n",
1453            ]
1454
1455            for item in iList:
1456                info.append("| {:<12} | {:<12} | {:<10} | {:>11} | {:>11} | {:>7}% | {:>19} | {:>19} | {:<5} |\n".format(
1457                    item["ticker"],
1458                    item["figi"],
1459                    item["type"],
1460                    "{:.2f}".format(float(item["currentPrice"]["closePrice"])),
1461                    "{:.2f}".format(float(item["currentPrice"]["lastPrice"])),
1462                    "{}{:.2f}".format("+" if item["currentPrice"]["changes"] > 0 else "", float(item["currentPrice"]["changes"])),
1463                    "{} / {}".format(
1464                        item["currentPrice"]["limitDown"] if item["currentPrice"]["limitDown"] is not None else "N/A",
1465                        item["currentPrice"]["limitUp"] if item["currentPrice"]["limitUp"] is not None else "N/A",
1466                    ),
1467                    "{} / {}".format(
1468                        item["currentPrice"]["sell"][0]["price"] if item["currentPrice"]["sell"] else "N/A",
1469                        item["currentPrice"]["buy"][0]["price"] if item["currentPrice"]["buy"] else "N/A",
1470                    ),
1471                    item["currency"],
1472                ))
1473
1474            infoText = "".join(info)
1475
1476            if show:
1477                uLogger.info("Only instruments with unique FIGIs are shown:\n{}".format(infoText))
1478
1479            if self.pricesFile:
1480                with open(self.pricesFile, "w", encoding="UTF-8") as fH:
1481                    fH.write(infoText)
1482
1483                uLogger.info("Price list for all instruments saved to file: [{}]".format(os.path.abspath(self.pricesFile)))
1484
1485        return infoText
1486
1487    def RequestTradingStatus(self) -> dict:
1488        """
1489        Requesting trading status for the instrument defined by `figi` variable.
1490        REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/MarketDataService/MarketDataService_GetTradingStatus
1491        Documentation: https://tinkoff.github.io/investAPI/marketdata/#gettradingstatusrequest
1492
1493        :return: dictionary with trading status attributes. Response example:
1494                 `{"figi": "TCS00A103X66", "tradingStatus": "SECURITY_TRADING_STATUS_NOT_AVAILABLE_FOR_TRADING",
1495                  "limitOrderAvailableFlag": false, "marketOrderAvailableFlag": false, "apiTradeAvailableFlag": true}`
1496        """
1497        if self.figi is None or not self.figi:
1498            uLogger.error("Variable `figi` must be defined for using this method!")
1499            raise Exception("FIGI required")
1500
1501        uLogger.debug("Requesting current trading status, FIGI: [{}]. Wait, please...".format(self.figi))
1502
1503        self.body = str({"figi": self.figi, "instrumentId": self.figi})
1504        tradingStatusURL = self.server + r"/tinkoff.public.invest.api.contract.v1.MarketDataService/GetTradingStatus"
1505        tradingStatus = self.SendAPIRequest(tradingStatusURL, reqType="POST")
1506
1507        if self.moreDebug:
1508            uLogger.debug("Records about current trading status successfully received")
1509
1510        return tradingStatus
1511
1512    def RequestPortfolio(self) -> dict:
1513        """
1514        Requesting actual user's portfolio for current `accountId`.
1515        REST API for user portfolio: https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetPortfolio
1516        Documentation: https://tinkoff.github.io/investAPI/operations/#portfoliorequest
1517
1518        :return: dictionary with user's portfolio.
1519        """
1520        if self.accountId is None or not self.accountId:
1521            uLogger.error("Variable `accountId` must be defined for using this method!")
1522            raise Exception("Account ID required")
1523
1524        uLogger.debug("Requesting current actual user's portfolio. Wait, please...")
1525
1526        self.body = str({"accountId": self.accountId})
1527        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OperationsService/GetPortfolio"
1528        rawPortfolio = self.SendAPIRequest(portfolioURL, reqType="POST")
1529
1530        if self.moreDebug:
1531            uLogger.debug("Records about user's portfolio successfully received")
1532
1533        return rawPortfolio
1534
1535    def RequestPositions(self) -> dict:
1536        """
1537        Requesting open positions by currencies and instruments for current `accountId`.
1538        REST API for open positions: https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetPositions
1539        Documentation: https://tinkoff.github.io/investAPI/operations/#positionsrequest
1540
1541        :return: dictionary with open positions by instruments.
1542        """
1543        if self.accountId is None or not self.accountId:
1544            uLogger.error("Variable `accountId` must be defined for using this method!")
1545            raise Exception("Account ID required")
1546
1547        uLogger.debug("Requesting current open positions in currencies and instruments. Wait, please...")
1548
1549        self.body = str({"accountId": self.accountId})
1550        positionsURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OperationsService/GetPositions"
1551        rawPositions = self.SendAPIRequest(positionsURL, reqType="POST")
1552
1553        if self.moreDebug:
1554            uLogger.debug("Records about current open positions successfully received")
1555
1556        return rawPositions
1557
1558    def RequestPendingOrders(self) -> list:
1559        """
1560        Requesting current actual pending orders for current `accountId`.
1561        REST API for pending (market) orders: https://tinkoff.github.io/investAPI/swagger-ui/#/OrdersService/OrdersService_GetOrders
1562        Documentation: https://tinkoff.github.io/investAPI/orders/#getordersrequest
1563
1564        :return: list of dictionaries with pending orders.
1565        """
1566        if self.accountId is None or not self.accountId:
1567            uLogger.error("Variable `accountId` must be defined for using this method!")
1568            raise Exception("Account ID required")
1569
1570        uLogger.debug("Requesting current actual pending orders. Wait, please...")
1571
1572        self.body = str({"accountId": self.accountId})
1573        ordersURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OrdersService/GetOrders"
1574        rawOrders = self.SendAPIRequest(ordersURL, reqType="POST")["orders"]
1575
1576        uLogger.debug("[{}] records about pending orders received".format(len(rawOrders)))
1577
1578        return rawOrders
1579
1580    def RequestStopOrders(self) -> list:
1581        """
1582        Requesting current actual stop orders for current `accountId`.
1583        REST API for opened stop-orders: https://tinkoff.github.io/investAPI/swagger-ui/#/StopOrdersService/StopOrdersService_GetStopOrders
1584        Documentation: https://tinkoff.github.io/investAPI/stoporders/#getstopordersrequest
1585
1586        :return: list of dictionaries with stop orders.
1587        """
1588        if self.accountId is None or not self.accountId:
1589            uLogger.error("Variable `accountId` must be defined for using this method!")
1590            raise Exception("Account ID required")
1591
1592        uLogger.debug("Requesting current actual stop orders. Wait, please...")
1593
1594        self.body = str({"accountId": self.accountId})
1595        ordersURL = self.server + r"/tinkoff.public.invest.api.contract.v1.StopOrdersService/GetStopOrders"
1596        rawStopOrders = self.SendAPIRequest(ordersURL, reqType="POST")["stopOrders"]
1597
1598        uLogger.debug("[{}] records about stop orders received".format(len(rawStopOrders)))
1599
1600        return rawStopOrders
1601
1602    def Overview(self, show: bool = False, details: str = "full") -> dict:
1603        """
1604        Get portfolio: all open positions, orders and some statistics for current `accountId`.
1605        If `overviewFile`, `overviewDigestFile`, `overviewPositionsFile`, `overviewOrdersFile`, `overviewAnalyticsFile`
1606        are defined then also save information to file.
1607
1608        WARNING! It is not recommended to run this method too many times in a loop! The server receives
1609        many requests about the state of the portfolio, and then, based on the received data, a large number
1610        of calculation and statistics are collected.
1611
1612        :param show: if `False` then only dictionary returns, if `True` then show more debug information.
1613        :param details: how detailed should the information be? You should specify one of strings:
1614                        `full` - shows full available information about portfolio status (by default),
1615                        `positions` - shows only open positions,
1616                        `digest` - show a short digest of the portfolio status,
1617                        `analytics` - shows only the analytics section and the distribution of the portfolio by various categories,
1618                        `orders` - shows only sections of open limits and stop orders.
1619        :return: dictionary with client's raw portfolio and some statistics.
1620        """
1621        if self.accountId is None or not self.accountId:
1622            uLogger.error("Variable `accountId` must be defined for using this method!")
1623            raise Exception("Account ID required")
1624
1625        view = {
1626            "raw": {  # --- raw portfolio responses from broker with user portfolio data:
1627                "headers": {},  # list of dictionaries, response headers without "positions" section
1628                "Currencies": [],  # list of dictionaries, open trades with currencies from "positions" section
1629                "Shares": [],  # list of dictionaries, open trades with shares from "positions" section
1630                "Bonds": [],  # list of dictionaries, open trades with bonds from "positions" section
1631                "Etfs": [],  # list of dictionaries, open trades with etfs from "positions" section
1632                "Futures": [],  # list of dictionaries, open trades with futures from "positions" section
1633                "positions": {},  # raw response from broker: dictionary with current available or blocked currencies and instruments for client
1634                "orders": [],  # raw response from broker: list of dictionaries with all pending (market) orders
1635                "stopOrders": [],  # raw response from broker: list of dictionaries with all stop orders
1636                "currenciesCurrentPrices": {"rub": {"name": "Российский рубль", "currentPrice": 1.}},  # dict with prices of all currencies in RUB
1637            },
1638            "stat": {  # --- some statistics calculated using "raw" sections:
1639                "portfolioCostRUB": 0.,  # portfolio cost in RUB (Russian Rouble)
1640                "availableRUB": 0.,  # available rubles (without other currencies)
1641                "blockedRUB": 0.,  # blocked sum in Russian Rouble
1642                "totalChangesRUB": 0.,  # changes for all open trades in RUB
1643                "totalChangesPercentRUB": 0.,  # changes for all open trades in percents
1644                "allCurrenciesCostRUB": 0.,  # costs of all currencies (include rubles) in RUB
1645                "sharesCostRUB": 0.,  # costs of all shares in RUB
1646                "bondsCostRUB": 0.,  # costs of all bonds in RUB
1647                "etfsCostRUB": 0.,  # costs of all etfs in RUB
1648                "futuresCostRUB": 0.,  # costs of all futures in RUB
1649                "Currencies": [],  # list of dictionaries of all currencies statistics
1650                "Shares": [],  # list of dictionaries of all shares statistics
1651                "Bonds": [],  # list of dictionaries of all bonds statistics
1652                "Etfs": [],  # list of dictionaries of all etfs statistics
1653                "Futures": [],  # list of dictionaries of all futures statistics
1654                "orders": [],  # list of dictionaries of all pending (market) orders and it's parameters
1655                "stopOrders": [],  # list of dictionaries of all stop orders and it's parameters
1656                "blockedCurrencies": {},  # dict with blocked instruments and currencies, e.g. {"rub": 1291.87, "usd": 6.21}
1657                "blockedInstruments": {},  # dict with blocked  by FIGI, e.g. {}
1658                "funds": {},  # dict with free funds for trading (total - blocked), by all currencies, e.g. {"rub": {"total": 10000.99, "totalCostRUB": 10000.99, "free": 1234.56, "freeCostRUB": 1234.56}, "usd": {"total": 250.55, "totalCostRUB": 15375.80, "free": 125.05, "freeCostRUB": 7687.50}}
1659            },
1660            "analytics": {  # --- some analytics of portfolio:
1661                "distrByAssets": {},  # portfolio distribution by assets
1662                "distrByCompanies": {},  # portfolio distribution by companies
1663                "distrBySectors": {},  # portfolio distribution by sectors
1664                "distrByCurrencies": {},  # portfolio distribution by currencies
1665                "distrByCountries": {},  # portfolio distribution by countries
1666            }
1667        }
1668
1669        details = details.lower()
1670        availableDetails = ["full", "positions", "digest", "analytics", "orders"]
1671        if details not in availableDetails:
1672            details = "full"
1673            uLogger.debug("Requested incorrect details! The `details` must be one of this strings: {}. Details parameter set to `full` be default.".format(availableDetails))
1674
1675        uLogger.debug("Requesting portfolio of a client. Wait, please...")
1676
1677        portfolioResponse = self.RequestPortfolio()  # current user's portfolio (dict)
1678        view["raw"]["positions"] = self.RequestPositions()  # current open positions by instruments (dict)
1679        view["raw"]["orders"] = self.RequestPendingOrders()  # current actual pending orders (list)
1680        view["raw"]["stopOrders"] = self.RequestStopOrders()  # current actual stop orders (list)
1681
1682        # save response headers without "positions" section:
1683        for key in portfolioResponse.keys():
1684            if key != "positions":
1685                view["raw"]["headers"][key] = portfolioResponse[key]
1686
1687            else:
1688                continue
1689
1690        # Re-sorting and separating given raw instruments and currencies by type: https://tinkoff.github.io/investAPI/operations/#operation
1691        # Type of instrument must be only one of supported types in TKS_INSTRUMENTS
1692        for item in portfolioResponse["positions"]:
1693            if item["instrumentType"] == "currency":
1694                self.figi = item["figi"]
1695                curr = self.SearchByFIGI(requestPrice=False)
1696
1697                # current price of currency in RUB:
1698                view["raw"]["currenciesCurrentPrices"][curr["nominal"]["currency"]] = {
1699                    "name": curr["name"],
1700                    "currentPrice": NanoToFloat(
1701                        item["currentPrice"]["units"],
1702                        item["currentPrice"]["nano"]
1703                    ),
1704                }
1705
1706                view["raw"]["Currencies"].append(item)
1707
1708            elif item["instrumentType"] == "share":
1709                view["raw"]["Shares"].append(item)
1710
1711            elif item["instrumentType"] == "bond":
1712                view["raw"]["Bonds"].append(item)
1713
1714            elif item["instrumentType"] == "etf":
1715                view["raw"]["Etfs"].append(item)
1716
1717            elif item["instrumentType"] == "futures":
1718                view["raw"]["Futures"].append(item)
1719
1720            else:
1721                continue
1722
1723        # how many volume of currencies (by ISO currency name) are blocked:
1724        for item in view["raw"]["positions"]["blocked"]:
1725            blocked = NanoToFloat(item["units"], item["nano"])
1726            if blocked > 0:
1727                view["stat"]["blockedCurrencies"][item["currency"]] = blocked
1728
1729        # how many volume of instruments (by FIGI) are blocked:
1730        for item in view["raw"]["positions"]["securities"]:
1731            blocked = int(item["blocked"])
1732            if blocked > 0:
1733                view["stat"]["blockedInstruments"][item["figi"]] = blocked
1734
1735        allBlocked = {**view["stat"]["blockedCurrencies"], **view["stat"]["blockedInstruments"]}
1736
1737        if "rub" in allBlocked.keys():
1738            view["stat"]["blockedRUB"] = allBlocked["rub"]  # blocked rubles
1739
1740        # --- saving current total amount in RUB of all currencies (with ruble), shares, bonds, etfs, futures and currencies:
1741        view["stat"]["allCurrenciesCostRUB"] = NanoToFloat(portfolioResponse["totalAmountCurrencies"]["units"], portfolioResponse["totalAmountCurrencies"]["nano"])
1742        view["stat"]["sharesCostRUB"] = NanoToFloat(portfolioResponse["totalAmountShares"]["units"], portfolioResponse["totalAmountShares"]["nano"])
1743        view["stat"]["bondsCostRUB"] = NanoToFloat(portfolioResponse["totalAmountBonds"]["units"], portfolioResponse["totalAmountBonds"]["nano"])
1744        view["stat"]["etfsCostRUB"] = NanoToFloat(portfolioResponse["totalAmountEtf"]["units"], portfolioResponse["totalAmountEtf"]["nano"])
1745        view["stat"]["futuresCostRUB"] = NanoToFloat(portfolioResponse["totalAmountFutures"]["units"], portfolioResponse["totalAmountFutures"]["nano"])
1746        view["stat"]["portfolioCostRUB"] = sum([
1747            view["stat"]["allCurrenciesCostRUB"],
1748            view["stat"]["sharesCostRUB"],
1749            view["stat"]["bondsCostRUB"],
1750            view["stat"]["etfsCostRUB"],
1751            view["stat"]["futuresCostRUB"],
1752        ])
1753
1754        # --- calculating some portfolio statistics:
1755        byComp = {}  # distribution by companies
1756        bySect = {}  # distribution by sectors
1757        byCurr = {}  # distribution by currencies (include RUB)
1758        unknownCountryName = "All other countries"  # default name for instruments without "countryOfRisk" and "countryOfRiskName"
1759        byCountry = {unknownCountryName: {"cost": 0, "percent": 0.}}  # distribution by countries (currencies are included in their countries)
1760
1761        for item in portfolioResponse["positions"]:
1762            self.figi = item["figi"]
1763            instrument = self.SearchByFIGI(requestPrice=False)  # full raw info about instrument by FIGI
1764
1765            if instrument:
1766                if item["instrumentType"] == "currency" and instrument["nominal"]["currency"] in allBlocked.keys():
1767                    blocked = allBlocked[instrument["nominal"]["currency"]]  # blocked volume of currency
1768
1769                elif item["instrumentType"] != "currency" and item["figi"] in allBlocked.keys():
1770                    blocked = allBlocked[item["figi"]]  # blocked volume of other instruments
1771
1772                else:
1773                    blocked = 0
1774
1775                volume = NanoToFloat(item["quantity"]["units"], item["quantity"]["nano"])  # available volume of instrument
1776                lots = NanoToFloat(item["quantityLots"]["units"], item["quantityLots"]["nano"])  # available volume in lots of instrument
1777                direction = "Long" if lots >= 0 else "Short"  # direction of an instrument's position: short or long
1778                curPrice = NanoToFloat(item["currentPrice"]["units"], item["currentPrice"]["nano"])  # current instrument's price
1779                average = NanoToFloat(item["averagePositionPriceFifo"]["units"], item["averagePositionPriceFifo"]["nano"])  # current average position price
1780                profit = NanoToFloat(item["expectedYield"]["units"], item["expectedYield"]["nano"])  # expected profit at current moment
1781                currency = instrument["currency"] if (item["instrumentType"] == "share" or item["instrumentType"] == "etf" or item["instrumentType"] == "future") else instrument["nominal"]["currency"]  # currency name rub, usd, eur etc.
1782                cost = (curPrice + NanoToFloat(item["currentNkd"]["units"], item["currentNkd"]["nano"])) * volume  # current cost of all volume of instrument in basic asset
1783                baseCurrencyName = item["currentPrice"]["currency"]  # name of base currency (rub)
1784                countryName = "[{}] {}".format(instrument["countryOfRisk"], instrument["countryOfRiskName"]) if "countryOfRisk" in instrument.keys() and "countryOfRiskName" in instrument.keys() and instrument["countryOfRisk"] and instrument["countryOfRiskName"] else unknownCountryName
1785                costRUB = cost if item["instrumentType"] == "currency" else cost * view["raw"]["currenciesCurrentPrices"][currency]["currentPrice"]  # cost in rubles
1786                percentCostRUB = 100 * costRUB / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.  # instrument's part in percent of full portfolio cost
1787
1788                statData = {
1789                    "figi": item["figi"],  # FIGI from REST API "GetPortfolio" method
1790                    "ticker": instrument["ticker"],  # ticker by FIGI
1791                    "currency": currency,  # currency name rub, usd, eur etc. for instrument price
1792                    "volume": volume,  # available volume of instrument
1793                    "lots": lots,  # volume in lots of instrument
1794                    "direction": direction,  # direction of an instrument's position: short or long
1795                    "blocked": blocked,  # blocked volume of currency or instrument
1796                    "currentPrice": curPrice,  # current instrument's price in basic asset
1797                    "average": average,  # current average position price
1798                    "cost": cost,  # current cost of all volume of instrument in basic asset
1799                    "baseCurrencyName": baseCurrencyName,  # name of base currency (rub)
1800                    "costRUB": costRUB,  # cost of instrument in ruble
1801                    "percentCostRUB": percentCostRUB,  # instrument's part in percent of full portfolio cost in RUB
1802                    "profit": profit,  # expected profit at current moment
1803                    "percentProfit": 100 * profit / (average * volume) if average != 0 and volume != 0 else 0,  # expected percents of profit at current moment for this instrument
1804                    "sector": instrument["sector"] if "sector" in instrument.keys() and instrument["sector"] else "other",
1805                    "name": instrument["name"] if "name" in instrument.keys() else "",  # human-readable names of instruments
1806                    "isoCurrencyName": instrument["isoCurrencyName"] if "isoCurrencyName" in instrument.keys() else "",  # ISO name for currencies only
1807                    "country": countryName,  # e.g. "[RU] Российская Федерация" or unknownCountryName
1808                    "step": instrument["step"],  # minimum price increment
1809                }
1810
1811                # adding distribution by unique countries:
1812                if statData["country"] not in byCountry.keys():
1813                    byCountry[statData["country"]] = {"cost": costRUB, "percent": percentCostRUB}
1814
1815                else:
1816                    byCountry[statData["country"]]["cost"] += costRUB
1817                    byCountry[statData["country"]]["percent"] += percentCostRUB
1818
1819                if item["instrumentType"] != "currency":
1820                    # adding distribution by unique companies:
1821                    if statData["name"]:
1822                        if statData["name"] not in byComp.keys():
1823                            byComp[statData["name"]] = {"ticker": statData["ticker"], "cost": costRUB, "percent": percentCostRUB}
1824
1825                        else:
1826                            byComp[statData["name"]]["cost"] += costRUB
1827                            byComp[statData["name"]]["percent"] += percentCostRUB
1828
1829                    # adding distribution by unique sectors:
1830                    if statData["sector"] not in bySect.keys():
1831                        bySect[statData["sector"]] = {"cost": costRUB, "percent": percentCostRUB}
1832
1833                    else:
1834                        bySect[statData["sector"]]["cost"] += costRUB
1835                        bySect[statData["sector"]]["percent"] += percentCostRUB
1836
1837                # adding distribution by unique currencies:
1838                if currency not in byCurr.keys():
1839                    byCurr[currency] = {
1840                        "name": view["raw"]["currenciesCurrentPrices"][currency]["name"],
1841                        "cost": costRUB,
1842                        "percent": percentCostRUB
1843                    }
1844
1845                else:
1846                    byCurr[currency]["cost"] += costRUB
1847                    byCurr[currency]["percent"] += percentCostRUB
1848
1849                # saving statistics for every instrument:
1850                if item["instrumentType"] == "currency":
1851                    view["stat"]["Currencies"].append(statData)
1852
1853                    # update dict with free funds for trading (total - blocked) by currencies
1854                    # e.g. {"rub": {"total": 10000.99, "totalCostRUB": 10000.99, "free": 1234.56, "freeCostRUB": 1234.56}, "usd": {"total": 250.55, "totalCostRUB": 15375.80, "free": 125.05, "freeCostRUB": 7687.50}}
1855                    view["stat"]["funds"][currency] = {
1856                        "total": volume,
1857                        "totalCostRUB": costRUB,  # total volume cost in rubles
1858                        "free": volume - blocked,
1859                        "freeCostRUB": costRUB * ((volume - blocked) / volume) if volume > 0 else 0,  # free volume cost in rubles
1860                    }
1861
1862                elif item["instrumentType"] == "share":
1863                    view["stat"]["Shares"].append(statData)
1864
1865                elif item["instrumentType"] == "bond":
1866                    view["stat"]["Bonds"].append(statData)
1867
1868                elif item["instrumentType"] == "etf":
1869                    view["stat"]["Etfs"].append(statData)
1870
1871                elif item["instrumentType"] == "Futures":
1872                    view["stat"]["Futures"].append(statData)
1873
1874                else:
1875                    continue
1876
1877        # total changes in Russian Ruble:
1878        view["stat"]["availableRUB"] = view["stat"]["allCurrenciesCostRUB"] - sum([item["cost"] for item in view["stat"]["Currencies"]])  # available RUB without other currencies
1879        view["stat"]["totalChangesPercentRUB"] = NanoToFloat(view["raw"]["headers"]["expectedYield"]["units"], view["raw"]["headers"]["expectedYield"]["nano"]) if "expectedYield" in view["raw"]["headers"].keys() else 0.
1880        startCost = view["stat"]["portfolioCostRUB"] / (1 + view["stat"]["totalChangesPercentRUB"] / 100)
1881        view["stat"]["totalChangesRUB"] = view["stat"]["portfolioCostRUB"] - startCost
1882        view["stat"]["funds"]["rub"] = {
1883            "total": view["stat"]["availableRUB"],
1884            "totalCostRUB": view["stat"]["availableRUB"],
1885            "free": view["stat"]["availableRUB"] - view["stat"]["blockedRUB"],
1886            "freeCostRUB": view["stat"]["availableRUB"] - view["stat"]["blockedRUB"],
1887        }
1888
1889        # --- pending orders sector data:
1890        uniquePendingOrders = []
1891        uniquePendingOrdersFIGIs = []
1892        for item in view["raw"]["orders"]:
1893            if item["figi"] not in uniquePendingOrdersFIGIs:
1894                uniquePendingOrdersFIGIs.append(item["figi"])
1895                uniquePendingOrders.append(item)
1896
1897        for item in uniquePendingOrders:
1898            self.figi = item["figi"]
1899            instrument = self.SearchByFIGI(requestPrice=True)  # full raw info about instrument by FIGI
1900
1901            if instrument:
1902                action = TKS_ORDER_DIRECTIONS[item["direction"]]
1903                orderType = TKS_ORDER_TYPES[item["orderType"]]
1904                orderState = TKS_ORDER_STATES[item["executionReportStatus"]]
1905                orderDate = item["orderDate"].replace("T", " ").replace("Z", "").split(".")[0]  # date in UTC format, e.g. "2022-12-31T23:59:59.123456Z"
1906
1907                # current instrument's price (last sellers order if buy, and last buyers order if sell):
1908                if item["direction"] == "ORDER_DIRECTION_BUY":
1909                    lastPrice = instrument["currentPrice"]["sell"][0]["price"] if instrument["currentPrice"]["sell"] else "N/A"
1910
1911                else:
1912                    lastPrice = instrument["currentPrice"]["buy"][0]["price"] if instrument["currentPrice"]["buy"] else "N/A"
1913
1914                # requested price for order execution:
1915                target = NanoToFloat(item["initialSecurityPrice"]["units"], item["initialSecurityPrice"]["nano"])
1916
1917                # necessary changes in percent to reach target from current price:
1918                changes = 100 * (lastPrice - target) / target if lastPrice != "N/A" and target > 0 else 0
1919
1920                view["stat"]["orders"].append({
1921                    "orderID": item["orderId"],  # orderId number parameter of current order
1922                    "figi": item["figi"],  # FIGI identification
1923                    "ticker": instrument["ticker"],  # ticker name by FIGI
1924                    "lotsRequested": item["lotsRequested"],  # requested lots value
1925                    "lotsExecuted": item["lotsExecuted"],  # how many lots are executed
1926                    "currentPrice": lastPrice,  # current instrument's price for defined action
1927                    "targetPrice": target,  # requested price for order execution in base currency
1928                    "baseCurrencyName": item["initialSecurityPrice"]["currency"],  # name of base currency
1929                    "percentChanges": changes,  # changes in percent to target from current price
1930                    "currency": item["currency"],  # instrument's currency name
1931                    "action": action,  # sell / buy / Unknown from TKS_ORDER_DIRECTIONS
1932                    "type": orderType,  # type of order from TKS_ORDER_TYPES
1933                    "status": orderState,  # order status from TKS_ORDER_STATES
1934                    "date": orderDate,  # string with order date and time from UTC format (without nano seconds part)
1935                })
1936
1937        # --- stop orders sector data:
1938        uniqueStopOrders = []
1939        uniqueStopOrdersFIGIs = []
1940        for item in view["raw"]["stopOrders"]:
1941            if item["figi"] not in uniqueStopOrdersFIGIs:
1942                uniqueStopOrdersFIGIs.append(item["figi"])
1943                uniqueStopOrders.append(item)
1944
1945        for item in uniqueStopOrders:
1946            self.figi = item["figi"]
1947            instrument = self.SearchByFIGI(requestPrice=True)  # full raw info about instrument by FIGI
1948
1949            if instrument:
1950                action = TKS_STOP_ORDER_DIRECTIONS[item["direction"]]
1951                orderType = TKS_STOP_ORDER_TYPES[item["orderType"]]
1952                createDate = item["createDate"].replace("T", " ").replace("Z", "").split(".")[0]  # date in UTC format, e.g. "2022-12-31T23:59:59.123456Z"
1953
1954                # hack: server response can't contain "expirationTime" key if it is not "Until date" type of stop order
1955                if "expirationTime" in item.keys():
1956                    expType = TKS_STOP_ORDER_EXPIRATION_TYPES["STOP_ORDER_EXPIRATION_TYPE_GOOD_TILL_DATE"]
1957                    expDate = item["expirationTime"].replace("T", " ").replace("Z", "").split(".")[0]
1958
1959                else:
1960                    expType = TKS_STOP_ORDER_EXPIRATION_TYPES["STOP_ORDER_EXPIRATION_TYPE_GOOD_TILL_CANCEL"]
1961                    expDate = TKS_STOP_ORDER_EXPIRATION_TYPES["STOP_ORDER_EXPIRATION_TYPE_UNSPECIFIED"]
1962
1963                # current instrument's price (last sellers order if buy, and last buyers order if sell):
1964                if item["direction"] == "STOP_ORDER_DIRECTION_BUY":
1965                    lastPrice = instrument["currentPrice"]["sell"][0]["price"] if instrument["currentPrice"]["sell"] else "N/A"
1966
1967                else:
1968                    lastPrice = instrument["currentPrice"]["buy"][0]["price"] if instrument["currentPrice"]["buy"] else "N/A"
1969
1970                # requested price when stop-order executed:
1971                target = NanoToFloat(item["stopPrice"]["units"], item["stopPrice"]["nano"])
1972
1973                # price for limit-order, set up when stop-order executed:
1974                limit = NanoToFloat(item["price"]["units"], item["price"]["nano"])
1975
1976                # necessary changes in percent to reach target from current price:
1977                changes = 100 * (lastPrice - target) / target if lastPrice != "N/A" and target > 0 else 0
1978
1979                view["stat"]["stopOrders"].append({
1980                    "orderID": item["stopOrderId"],  # stopOrderId number parameter of current stop-order
1981                    "figi": item["figi"],  # FIGI identification
1982                    "ticker": instrument["ticker"],  # ticker name by FIGI
1983                    "lotsRequested": item["lotsRequested"],  # requested lots value
1984                    "currentPrice": lastPrice,  # current instrument's price for defined action
1985                    "targetPrice": target,  # requested price for stop-order execution in base currency
1986                    "limitPrice": limit,  # price for limit-order, set up when stop-order executed, 0 if market order
1987                    "baseCurrencyName": item["stopPrice"]["currency"],  # name of base currency
1988                    "percentChanges": changes,  # changes in percent to target from current price
1989                    "currency": item["currency"],  # instrument's currency name
1990                    "action": action,  # sell / buy / Unknown from TKS_STOP_ORDER_DIRECTIONS
1991                    "type": orderType,  # type of order from TKS_STOP_ORDER_TYPES
1992                    "expType": expType,  # expiration type of stop-order from TKS_STOP_ORDER_EXPIRATION_TYPES
1993                    "createDate": createDate,  # string with created order date and time from UTC format (without nano seconds part)
1994                    "expDate": expDate,  # string with expiration order date and time from UTC format (without nano seconds part)
1995                })
1996
1997        # --- calculating data for analytics section:
1998        # portfolio distribution by assets:
1999        view["analytics"]["distrByAssets"] = {
2000            "Ruble": {
2001                "uniques": 1,
2002                "cost": view["stat"]["availableRUB"],
2003                "percent": 100 * view["stat"]["availableRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2004            },
2005            "Currencies": {
2006                "uniques": len(view["stat"]["Currencies"]),  # all foreign currencies without RUB
2007                "cost": view["stat"]["allCurrenciesCostRUB"] - view["stat"]["availableRUB"],
2008                "percent": 100 * (view["stat"]["allCurrenciesCostRUB"] - view["stat"]["availableRUB"]) / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2009            },
2010            "Shares": {
2011                "uniques": len(view["stat"]["Shares"]),
2012                "cost": view["stat"]["sharesCostRUB"],
2013                "percent": 100 * view["stat"]["sharesCostRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2014            },
2015            "Bonds": {
2016                "uniques": len(view["stat"]["Bonds"]),
2017                "cost": view["stat"]["bondsCostRUB"],
2018                "percent": 100 * view["stat"]["bondsCostRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2019            },
2020            "Etfs": {
2021                "uniques": len(view["stat"]["Etfs"]),
2022                "cost": view["stat"]["etfsCostRUB"],
2023                "percent": 100 * view["stat"]["etfsCostRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2024            },
2025            "Futures": {
2026                "uniques": len(view["stat"]["Futures"]),
2027                "cost": view["stat"]["futuresCostRUB"],
2028                "percent": 100 * view["stat"]["futuresCostRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2029            },
2030        }
2031
2032        # portfolio distribution by companies:
2033        view["analytics"]["distrByCompanies"]["All money cash"] = {
2034            "ticker": "",
2035            "cost": view["stat"]["allCurrenciesCostRUB"],
2036            "percent": 100 * view["stat"]["allCurrenciesCostRUB"] / view["stat"]["portfolioCostRUB"] if view["stat"]["portfolioCostRUB"] > 0 else 0.,
2037        }
2038        view["analytics"]["distrByCompanies"].update(byComp)
2039
2040        # portfolio distribution by sectors:
2041        view["analytics"]["distrBySectors"]["All money cash"] = {
2042            "cost": view["analytics"]["distrByCompanies"]["All money cash"]["cost"],
2043            "percent": view["analytics"]["distrByCompanies"]["All money cash"]["percent"],
2044        }
2045        view["analytics"]["distrBySectors"].update(bySect)
2046
2047        # portfolio distribution by currencies:
2048        if "rub" not in view["analytics"]["distrByCurrencies"].keys():
2049            uLogger.debug("Fast hack to avoid issues #71 in `Portfolio distribution by currencies` section. Server not returned current available rubles!")
2050            view["analytics"]["distrByCurrencies"]["rub"] = {"name": "Российский рубль", "cost": 0, "percent": 0}
2051
2052        view["analytics"]["distrByCurrencies"].update(byCurr)
2053        view["analytics"]["distrByCurrencies"]["rub"]["cost"] += view["analytics"]["distrByAssets"]["Ruble"]["cost"]
2054        view["analytics"]["distrByCurrencies"]["rub"]["percent"] += view["analytics"]["distrByAssets"]["Ruble"]["percent"]
2055
2056        # portfolio distribution by countries:
2057        if "[RU] Российская Федерация" not in view["analytics"]["distrByCountries"].keys():
2058            uLogger.debug("Fast hack to avoid issues #71 in `Portfolio distribution by countries` section. Server not returned current available rubles!")
2059            view["analytics"]["distrByCountries"]["[RU] Российская Федерация"] = {"cost": 0, "percent": 0}
2060
2061        view["analytics"]["distrByCountries"].update(byCountry)
2062        view["analytics"]["distrByCountries"]["[RU] Российская Федерация"]["cost"] += view["analytics"]["distrByAssets"]["Ruble"]["cost"]
2063        view["analytics"]["distrByCountries"]["[RU] Российская Федерация"]["percent"] += view["analytics"]["distrByAssets"]["Ruble"]["percent"]
2064
2065        # --- Prepare text statistics overview in human-readable:
2066        if show:
2067            # Whatever the value `details`, header not changes:
2068            info = [
2069                "# Client's portfolio\n\n",
2070                "* **Actual date:** [{} UTC]\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
2071                "* **Account ID:** [{}]\n".format(self.accountId),
2072            ]
2073
2074            if details in ["full", "positions", "digest"]:
2075                info.extend([
2076                    "* **Portfolio cost:** {:.2f} RUB\n".format(view["stat"]["portfolioCostRUB"]),
2077                    "* **Changes:** {}{:.2f} RUB ({}{:.2f}%)\n\n".format(
2078                        "+" if view["stat"]["totalChangesRUB"] > 0 else "",
2079                        view["stat"]["totalChangesRUB"],
2080                        "+" if view["stat"]["totalChangesPercentRUB"] > 0 else "",
2081                        view["stat"]["totalChangesPercentRUB"],
2082                    ),
2083                ])
2084
2085            if details in ["full", "positions"]:
2086                info.extend([
2087                    "## Open positions\n\n",
2088                    "| Ticker [FIGI]               | Volume (blocked)                | Lots     | Curr. price  | Avg. price   | Current volume cost | Profit (%)                   |\n",
2089                    "|-----------------------------|---------------------------------|----------|--------------|--------------|---------------------|------------------------------|\n",
2090                    "| Ruble                       | {:>31} |          |              |              |                     |                              |\n".format(
2091                        "{:.2f} ({:.2f}) rub".format(
2092                            view["stat"]["availableRUB"],
2093                            view["stat"]["blockedRUB"],
2094                        )
2095                    )
2096                ])
2097
2098                def _SplitStr(CostRUB: float = 0, typeStr: str = "", noTradeStr: str = "") -> list:
2099                    return [
2100                        "|                             |                                 |          |              |              |                     |                              |\n",
2101                        "| {:<27} |                                 |          |              |              | {:>19} |                              |\n".format(
2102                            noTradeStr if noTradeStr else typeStr,
2103                            "" if noTradeStr else "{:.2f} RUB".format(CostRUB),
2104                        ),
2105                    ]
2106
2107                def _InfoStr(data: dict, showCurrencyName: bool = False) -> str:
2108                    return "| {:<27} | {:>31} | {:<8} | {:>12} | {:>12} | {:>19} | {:<28} |\n".format(
2109                        "{} [{}]".format(data["ticker"], data["figi"]),
2110                        "{:.2f} ({:.2f}) {}".format(
2111                            data["volume"],
2112                            data["blocked"],
2113                            data["currency"],
2114                        ) if showCurrencyName else "{:.0f} ({:.0f})".format(
2115                            data["volume"],
2116                            data["blocked"],
2117                        ),
2118                        "{:.4f}".format(data["lots"]) if showCurrencyName else "{:.0f}".format(data["lots"]),
2119                        "{:.2f} {}".format(data["currentPrice"], data["baseCurrencyName"]) if data["currentPrice"] > 0 else "n/a",
2120                        "{:.2f} {}".format(data["average"], data["baseCurrencyName"]) if data["average"] > 0 else "n/a",
2121                        "{:.2f} {}".format(data["cost"], data["baseCurrencyName"]),
2122                        "{}{:.2f} {} ({}{:.2f}%)".format(
2123                            "+" if data["profit"] > 0 else "",
2124                            data["profit"], data["baseCurrencyName"],
2125                            "+" if data["percentProfit"] > 0 else "",
2126                            data["percentProfit"],
2127                        ),
2128                    )
2129
2130                # --- Show currencies section:
2131                if view["stat"]["Currencies"]:
2132                    info.extend(_SplitStr(CostRUB=view["analytics"]["distrByAssets"]["Currencies"]["cost"], typeStr="**Currencies:**"))
2133                    for item in view["stat"]["Currencies"]:
2134                        info.append(_InfoStr(item, showCurrencyName=True))
2135
2136                else:
2137                    info.extend(_SplitStr(noTradeStr="**Currencies:** no trades"))
2138
2139                # --- Show shares section:
2140                if view["stat"]["Shares"]:
2141                    info.extend(_SplitStr(CostRUB=view["stat"]["sharesCostRUB"], typeStr="**Shares:**"))
2142
2143                    for item in view["stat"]["Shares"]:
2144                        info.append(_InfoStr(item))
2145
2146                else:
2147                    info.extend(_SplitStr(noTradeStr="**Shares:** no trades"))
2148
2149                # --- Show bonds section:
2150                if view["stat"]["Bonds"]:
2151                    info.extend(_SplitStr(CostRUB=view["stat"]["bondsCostRUB"], typeStr="**Bonds:**"))
2152
2153                    for item in view["stat"]["Bonds"]:
2154                        info.append(_InfoStr(item))
2155
2156                else:
2157                    info.extend(_SplitStr(noTradeStr="**Bonds:** no trades"))
2158
2159                # --- Show etfs section:
2160                if view["stat"]["Etfs"]:
2161                    info.extend(_SplitStr(CostRUB=view["stat"]["etfsCostRUB"], typeStr="**Etfs:**"))
2162
2163                    for item in view["stat"]["Etfs"]:
2164                        info.append(_InfoStr(item))
2165
2166                else:
2167                    info.extend(_SplitStr(noTradeStr="**Etfs:** no trades"))
2168
2169                # --- Show futures section:
2170                if view["stat"]["Futures"]:
2171                    info.extend(_SplitStr(CostRUB=view["stat"]["futuresCostRUB"], typeStr="**Futures:**"))
2172
2173                    for item in view["stat"]["Futures"]:
2174                        info.append(_InfoStr(item))
2175
2176                else:
2177                    info.extend(_SplitStr(noTradeStr="**Futures:** no trades"))
2178
2179            if details in ["full", "orders"]:
2180                # --- Show pending orders section:
2181                if view["stat"]["orders"]:
2182                    info.extend([
2183                        "\n## Opened pending limit-orders: {}\n".format(len(view["stat"]["orders"])),
2184                        "\n| Ticker [FIGI]               | Order ID       | Lots (exec.) | Current price (% delta) | Target price  | Action    | Type      | Create date (UTC)       |\n",
2185                        "|-----------------------------|----------------|--------------|-------------------------|---------------|-----------|-----------|-------------------------|\n",
2186                    ])
2187
2188                    for item in view["stat"]["orders"]:
2189                        info.append("| {:<27} | {:<14} | {:<12} | {:>23} | {:>13} | {:<9} | {:<9} | {:<23} |\n".format(
2190                            "{} [{}]".format(item["ticker"], item["figi"]),
2191                            item["orderID"],
2192                            "{} ({})".format(item["lotsRequested"], item["lotsExecuted"]),
2193                            "{} {} ({}{:.2f}%)".format(
2194                                "{}".format(item["currentPrice"]) if isinstance(item["currentPrice"], str) else "{:.2f}".format(float(item["currentPrice"])),
2195                                item["baseCurrencyName"],
2196                                "+" if item["percentChanges"] > 0 else "",
2197                                float(item["percentChanges"]),
2198                            ),
2199                            "{:.2f} {}".format(float(item["targetPrice"]), item["baseCurrencyName"]),
2200                            item["action"],
2201                            item["type"],
2202                            item["date"],
2203                        ))
2204
2205                else:
2206                    info.append("\n## Total pending limit-orders: 0\n")
2207
2208                # --- Show stop orders section:
2209                if view["stat"]["stopOrders"]:
2210                    info.extend([
2211                        "\n## Opened stop-orders: {}\n".format(len(view["stat"]["stopOrders"])),
2212                        "\n| Ticker [FIGI]               | Stop order ID                        | Lots   | Current price (% delta) | Target price  | Limit price   | Action    | Type        | Expire type  | Create date (UTC)   | Expiration (UTC)    |\n",
2213                        "|-----------------------------|--------------------------------------|--------|-------------------------|---------------|---------------|-----------|-------------|--------------|---------------------|---------------------|\n",
2214                    ])
2215
2216                    for item in view["stat"]["stopOrders"]:
2217                        info.append("| {:<27} | {:<14} | {:<6} | {:>23} | {:>13} | {:>13} | {:<9} | {:<11} | {:<12} | {:<19} | {:<19} |\n".format(
2218                            "{} [{}]".format(item["ticker"], item["figi"]),
2219                            item["orderID"],
2220                            item["lotsRequested"],
2221                            "{} {} ({}{:.2f}%)".format(
2222                                "{}".format(item["currentPrice"]) if isinstance(item["currentPrice"], str) else "{:.2f}".format(float(item["currentPrice"])),
2223                                item["baseCurrencyName"],
2224                                "+" if item["percentChanges"] > 0 else "",
2225                                float(item["percentChanges"]),
2226                            ),
2227                            "{:.2f} {}".format(float(item["targetPrice"]), item["baseCurrencyName"]),
2228                            "{:.2f} {}".format(float(item["limitPrice"]), item["baseCurrencyName"]) if item["limitPrice"] and item["limitPrice"] != item["targetPrice"] else TKS_ORDER_TYPES["ORDER_TYPE_MARKET"],
2229                            item["action"],
2230                            item["type"],
2231                            item["expType"],
2232                            item["createDate"],
2233                            item["expDate"],
2234                        ))
2235
2236                else:
2237                    info.append("\n## Total stop-orders: 0\n")
2238
2239            if details in ["full", "analytics"]:
2240                # -- Show analytics section:
2241                if view["stat"]["portfolioCostRUB"] > 0:
2242                    info.extend([
2243                        "\n# Analytics\n"
2244                        "\n* **Current total portfolio cost:** {:.2f} RUB\n".format(view["stat"]["portfolioCostRUB"]),
2245                        "* **Changes:** {}{:.2f} RUB ({}{:.2f}%)\n".format(
2246                            "+" if view["stat"]["totalChangesRUB"] > 0 else "",
2247                            view["stat"]["totalChangesRUB"],
2248                            "+" if view["stat"]["totalChangesPercentRUB"] > 0 else "",
2249                            view["stat"]["totalChangesPercentRUB"],
2250                        ),
2251                        "\n## Portfolio distribution by assets\n"
2252                        "\n| Type       | Uniques | Percent | Current cost       |\n",
2253                        "|------------|---------|---------|--------------------|\n",
2254                    ])
2255
2256                    for key in view["analytics"]["distrByAssets"].keys():
2257                        if view["analytics"]["distrByAssets"][key]["cost"] > 0:
2258                            info.append("| {:<10} | {:<7} | {:<7} | {:<18} |\n".format(
2259                                key,
2260                                view["analytics"]["distrByAssets"][key]["uniques"],
2261                                "{:.2f}%".format(view["analytics"]["distrByAssets"][key]["percent"]),
2262                                "{:.2f} rub".format(view["analytics"]["distrByAssets"][key]["cost"]),
2263                            ))
2264
2265                    maxLenNames = 3 + max([len(company) + len(view["analytics"]["distrByCompanies"][company]["ticker"]) for company in view["analytics"]["distrByCompanies"].keys()])
2266                    info.extend([
2267                        "\n## Portfolio distribution by companies\n"
2268                        "\n| Company{} | Percent | Current cost       |\n".format(" " * (maxLenNames - 7)),
2269                        "|--------{}-|---------|--------------------|\n".format("-" * (maxLenNames - 7)),
2270                    ])
2271
2272                    for company in view["analytics"]["distrByCompanies"].keys():
2273                        if view["analytics"]["distrByCompanies"][company]["cost"] > 0:
2274                            nameLen = len(company) + len(view["analytics"]["distrByCompanies"][company]["ticker"])
2275                            info.append("| {} | {:<7} | {:<18} |\n".format(
2276                                "{}{}{}".format(
2277                                    "[{}] ".format(view["analytics"]["distrByCompanies"][company]["ticker"]) if view["analytics"]["distrByCompanies"][company]["ticker"] else "",
2278                                    company,
2279                                    "" if nameLen == maxLenNames else "{}".format(" " * (maxLenNames - nameLen - 3) if view["analytics"]["distrByCompanies"][company]["ticker"] else " " * (maxLenNames - nameLen)),
2280                                ),
2281                                "{:.2f}%".format(view["analytics"]["distrByCompanies"][company]["percent"]),
2282                                "{:.2f} rub".format(view["analytics"]["distrByCompanies"][company]["cost"]),
2283                            ))
2284
2285                    maxLenSectors = max([len(sector) for sector in view["analytics"]["distrBySectors"].keys()])
2286                    info.extend([
2287                        "\n## Portfolio distribution by sectors\n"
2288                        "\n| Sector{} | Percent | Current cost       |\n".format(" " * (maxLenSectors - 6)),
2289                        "|-------{}-|---------|--------------------|\n".format("-" * (maxLenSectors - 6)),
2290                    ])
2291
2292                    for sector in view["analytics"]["distrBySectors"].keys():
2293                        if view["analytics"]["distrBySectors"][sector]["cost"] > 0:
2294                            info.append("| {}{} | {:<7} | {:<18} |\n".format(
2295                                sector,
2296                                "" if len(sector) == maxLenSectors else " " * (maxLenSectors - len(sector)),
2297                                "{:.2f}%".format(view["analytics"]["distrBySectors"][sector]["percent"]),
2298                                "{:.2f} rub".format(view["analytics"]["distrBySectors"][sector]["cost"]),
2299                            ))
2300
2301                    maxLenMoney = 3 + max([len(currency) + len(view["analytics"]["distrByCurrencies"][currency]["name"]) for currency in view["analytics"]["distrByCurrencies"].keys()])
2302                    info.extend([
2303                        "\n## Portfolio distribution by currencies\n"
2304                        "\n| Instruments currencies{} | Percent | Current cost       |\n".format(" " * (maxLenMoney - 22)),
2305                        "|-----------------------{}-|---------|--------------------|\n".format("-" * (maxLenMoney - 22)),
2306                    ])
2307
2308                    for curr in view["analytics"]["distrByCurrencies"].keys():
2309                        if view["analytics"]["distrByCurrencies"][curr]["cost"] > 0:
2310                            nameLen = 3 + len(curr) + len(view["analytics"]["distrByCurrencies"][curr]["name"])
2311                            info.append("| {} | {:<7} | {:<18} |\n".format(
2312                                "[{}] {}{}".format(
2313                                    curr,
2314                                    view["analytics"]["distrByCurrencies"][curr]["name"],
2315                                    "" if nameLen == maxLenMoney else " " * (maxLenMoney - nameLen),
2316                                ),
2317                                "{:.2f}%".format(view["analytics"]["distrByCurrencies"][curr]["percent"]),
2318                                "{:.2f} rub".format(view["analytics"]["distrByCurrencies"][curr]["cost"]),
2319                            ))
2320
2321                    maxLenCountry = max(17, max([len(country) for country in view["analytics"]["distrByCountries"].keys()]))
2322                    info.extend([
2323                        "\n## Portfolio distribution by countries\n"
2324                        "\n| Assets by country{} | Percent | Current cost       |\n".format(" " * (maxLenCountry - 17)),
2325                        "|------------------{}-|---------|--------------------|\n".format("-" * (maxLenCountry - 17)),
2326                    ])
2327
2328                    for country in view["analytics"]["distrByCountries"].keys():
2329                        if view["analytics"]["distrByCountries"][country]["cost"] > 0:
2330                            nameLen = len(country)
2331                            info.append("| {} | {:<7} | {:<18} |\n".format(
2332                                "{}{}".format(
2333                                    country,
2334                                    "" if nameLen == maxLenCountry else " " * (maxLenCountry - nameLen),
2335                                ),
2336                                "{:.2f}%".format(view["analytics"]["distrByCountries"][country]["percent"]),
2337                                "{:.2f} rub".format(view["analytics"]["distrByCountries"][country]["cost"]),
2338                            ))
2339
2340            infoText = "".join(info)
2341
2342            uLogger.info(infoText)
2343
2344            if details == "full" and self.overviewFile:
2345                filename = self.overviewFile
2346
2347            elif details == "digest" and self.overviewDigestFile:
2348                filename = self.overviewDigestFile
2349
2350            elif details == "positions" and self.overviewPositionsFile:
2351                filename = self.overviewPositionsFile
2352
2353            elif details == "orders" and self.overviewOrdersFile:
2354                filename = self.overviewOrdersFile
2355
2356            elif details == "analytics" and self.overviewAnalyticsFile:
2357                filename = self.overviewAnalyticsFile
2358
2359            else:
2360                filename = ""
2361
2362            if filename:
2363                with open(filename, "w", encoding="UTF-8") as fH:
2364                    fH.write(infoText)
2365
2366                uLogger.info("Client's portfolio was saved to file: [{}]".format(os.path.abspath(filename)))
2367
2368        return view
2369
2370    def Deals(self, start: str = None, end: str = None, show: bool = False, showCancelled: bool = True) -> tuple[list[dict], dict]:
2371        """
2372        Returns history operations between two given dates for current `accountId`.
2373        If `reportFile` string is not empty then also save human-readable report.
2374        Shows some statistical data of closed positions.
2375
2376        :param start: see docstring in `GetDatesAsString()` method
2377        :param end: see docstring in `GetDatesAsString()` method
2378        :param show: if `True` then also prints all records to the console.
2379        :param showCancelled: if `False` then remove information about cancelled operations from the deals report.
2380        :return: original list of dictionaries with history of deals records from API ("operations" key):
2381                 https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetOperations
2382                 and dictionary with custom stats: operations in different currencies, withdrawals, incomes etc.
2383        """
2384        if self.accountId is None or not self.accountId:
2385            uLogger.error("Variable `accountId` must be defined for using this method!")
2386            raise Exception("Account ID required")
2387
2388        startDate, endDate = GetDatesAsString(start, end)  # Example: ("2000-01-01T00:00:00Z", "2022-12-31T23:59:59Z")
2389
2390        uLogger.debug("Requesting history of a client's operations. Wait, please...")
2391
2392        # REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetOperations
2393        dealsURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OperationsService/GetOperations"
2394        self.body = str({"accountId": self.accountId, "from": startDate, "to": endDate})
2395        ops = self.SendAPIRequest(dealsURL, reqType="POST")["operations"]  # list of dict: operations returns by broker
2396        customStat = {}  # custom statistics in additional to responseJSON
2397
2398        # --- output report in human-readable format:
2399        if show or self.reportFile:
2400            splitLine1 = "|                            |                               |                              |                      |                        |\n"  # Summary section
2401            splitLine2 = "|                     |              |              |            |           |                 |            |                                                                    |\n"  # Operations section
2402            nextDay = ""
2403
2404            info = ["# Client's operations\n\n* **Period:** from [{}] to [{}]\n\n## Summary (operations executed only)\n\n".format(startDate.split("T")[0], endDate.split("T")[0])]
2405
2406            if len(ops) > 0:
2407                customStat = {
2408                    "opsCount": 0,  # total operations count
2409                    "buyCount": 0,  # buy operations
2410                    "sellCount": 0,  # sell operations
2411                    "buyTotal": {"rub": 0.},  # Buy sums in different currencies
2412                    "sellTotal": {"rub": 0.},  # Sell sums in different currencies
2413                    "payIn": {"rub": 0.},  # Deposit brokerage account
2414                    "payOut": {"rub": 0.},  # Withdrawals
2415                    "divs": {"rub": 0.},  # Dividends income
2416                    "coupons": {"rub": 0.},  # Coupon's income
2417                    "brokerCom": {"rub": 0.},  # Service commissions
2418                    "serviceCom": {"rub": 0.},  # Service commissions
2419                    "marginCom": {"rub": 0.},  # Margin commissions
2420                    "allTaxes": {"rub": 0.},  # Sum of withholding taxes and corrections
2421                }
2422
2423                # --- calculating statistics depends on operations type in TKS_OPERATION_TYPES:
2424                for item in ops:
2425                    if item["state"] == "OPERATION_STATE_EXECUTED":
2426                        payment = NanoToFloat(item["payment"]["units"], item["payment"]["nano"])
2427
2428                        # count buy operations:
2429                        if "_BUY" in item["operationType"]:
2430                            customStat["buyCount"] += 1
2431
2432                            if item["payment"]["currency"] in customStat["buyTotal"].keys():
2433                                customStat["buyTotal"][item["payment"]["currency"]] += payment
2434
2435                            else:
2436                                customStat["buyTotal"][item["payment"]["currency"]] = payment
2437
2438                        # count sell operations:
2439                        elif "_SELL" in item["operationType"]:
2440                            customStat["sellCount"] += 1
2441
2442                            if item["payment"]["currency"] in customStat["sellTotal"].keys():
2443                                customStat["sellTotal"][item["payment"]["currency"]] += payment
2444
2445                            else:
2446                                customStat["sellTotal"][item["payment"]["currency"]] = payment
2447
2448                        # count incoming operations:
2449                        elif item["operationType"] in ["OPERATION_TYPE_INPUT"]:
2450                            if item["payment"]["currency"] in customStat["payIn"].keys():
2451                                customStat["payIn"][item["payment"]["currency"]] += payment
2452
2453                            else:
2454                                customStat["payIn"][item["payment"]["currency"]] = payment
2455
2456                        # count withdrawals operations:
2457                        elif item["operationType"] in ["OPERATION_TYPE_OUTPUT"]:
2458                            if item["payment"]["currency"] in customStat["payOut"].keys():
2459                                customStat["payOut"][item["payment"]["currency"]] += payment
2460
2461                            else:
2462                                customStat["payOut"][item["payment"]["currency"]] = payment
2463
2464                        # count dividends income:
2465                        elif item["operationType"] in ["OPERATION_TYPE_DIVIDEND", "OPERATION_TYPE_DIVIDEND_TRANSFER", "OPERATION_TYPE_DIV_EXT"]:
2466                            if item["payment"]["currency"] in customStat["divs"].keys():
2467                                customStat["divs"][item["payment"]["currency"]] += payment
2468
2469                            else:
2470                                customStat["divs"][item["payment"]["currency"]] = payment
2471
2472                        # count coupon's income:
2473                        elif item["operationType"] in ["OPERATION_TYPE_COUPON", "OPERATION_TYPE_BOND_REPAYMENT_FULL", "OPERATION_TYPE_BOND_REPAYMENT"]:
2474                            if item["payment"]["currency"] in customStat["coupons"].keys():
2475                                customStat["coupons"][item["payment"]["currency"]] += payment
2476
2477                            else:
2478                                customStat["coupons"][item["payment"]["currency"]] = payment
2479
2480                        # count broker commissions:
2481                        elif item["operationType"] in ["OPERATION_TYPE_BROKER_FEE", "OPERATION_TYPE_SUCCESS_FEE", "OPERATION_TYPE_TRACK_MFEE", "OPERATION_TYPE_TRACK_PFEE"]:
2482                            if item["payment"]["currency"] in customStat["brokerCom"].keys():
2483                                customStat["brokerCom"][item["payment"]["currency"]] += payment
2484
2485                            else:
2486                                customStat["brokerCom"][item["payment"]["currency"]] = payment
2487
2488                        # count service commissions:
2489                        elif item["operationType"] in ["OPERATION_TYPE_SERVICE_FEE"]:
2490                            if item["payment"]["currency"] in customStat["serviceCom"].keys():
2491                                customStat["serviceCom"][item["payment"]["currency"]] += payment
2492
2493                            else:
2494                                customStat["serviceCom"][item["payment"]["currency"]] = payment
2495
2496                        # count margin commissions:
2497                        elif item["operationType"] in ["OPERATION_TYPE_MARGIN_FEE"]:
2498                            if item["payment"]["currency"] in customStat["marginCom"].keys():
2499                                customStat["marginCom"][item["payment"]["currency"]] += payment
2500
2501                            else:
2502                                customStat["marginCom"][item["payment"]["currency"]] = payment
2503
2504                        # count withholding taxes:
2505                        elif "_TAX" in item["operationType"]:
2506                            if item["payment"]["currency"] in customStat["allTaxes"].keys():
2507                                customStat["allTaxes"][item["payment"]["currency"]] += payment
2508
2509                            else:
2510                                customStat["allTaxes"][item["payment"]["currency"]] = payment
2511
2512                        else:
2513                            continue
2514
2515                customStat["opsCount"] += customStat["buyCount"] + customStat["sellCount"]
2516
2517                # --- view "Actions" lines:
2518                info.extend([
2519                    "| Report sections            |                               |                              |                      |                        |\n",
2520                    "|----------------------------|-------------------------------|------------------------------|----------------------|------------------------|\n",
2521                    "| **Actions:**               | Trades: {:<21} | Trading volumes:             |                      |                        |\n".format(customStat["opsCount"]),
2522                    "|                            |   Buy: {:<22} | {:<28} |                      |                        |\n".format(
2523                        "{} ({:.1f}%)".format(customStat["buyCount"], 100 * customStat["buyCount"] / customStat["opsCount"]) if customStat["opsCount"] != 0 else 0,
2524                        "  rub, buy: {:<16}".format("{:.2f}".format(customStat["buyTotal"]["rub"])) if customStat["buyTotal"]["rub"] != 0 else "  —",
2525                    ),
2526                    "|                            |   Sell: {:<21} | {:<28} |                      |                        |\n".format(
2527                        "{} ({:.1f}%)".format(customStat["sellCount"], 100 * customStat["sellCount"] / customStat["opsCount"]) if customStat["opsCount"] != 0 else 0,
2528                        "  rub, sell: {:<13}".format("+{:.2f}".format(customStat["sellTotal"]["rub"])) if customStat["sellTotal"]["rub"] != 0 else "  —",
2529                    ),
2530                ])
2531
2532                opsKeys = sorted(list(set(list(customStat["buyTotal"].keys()) + list(customStat["sellTotal"].keys()))))
2533                for key in opsKeys:
2534                    if key == "rub":
2535                        continue
2536
2537                    info.extend([
2538                        "|                            |                               | {:<28} |                      |                        |\n".format(
2539                            "  {}, buy: {:<16}".format(key, "{:.2f}".format(customStat["buyTotal"][key]) if key and key in customStat["buyTotal"].keys() and customStat["buyTotal"][key] != 0 else 0)
2540                        ),
2541                        "|                            |                               | {:<28} |                      |                        |\n".format(
2542                            "  {}, sell: {:<13}".format(key, "+{:.2f}".format(customStat["sellTotal"][key]) if key and key in customStat["sellTotal"].keys() and customStat["sellTotal"][key] != 0 else 0)
2543                        ),
2544                    ])
2545
2546                info.append(splitLine1)
2547
2548                def _InfoStr(data1: dict, data2: dict, data3: dict, data4: dict, cur: str = "") -> str:
2549                    return "|                            | {:<29} | {:<28} | {:<20} | {:<22} |\n".format(
2550                            "  {}: {}{:.2f}".format(cur, "+" if data1[cur] > 0 else "", data1[cur]) if cur and cur in data1.keys() and data1[cur] != 0 else "  —",
2551                            "  {}: {}{:.2f}".format(cur, "+" if data2[cur] > 0 else "", data2[cur]) if cur and cur in data2.keys() and data2[cur] != 0 else "  —",
2552                            "  {}: {}{:.2f}".format(cur, "+" if data3[cur] > 0 else "", data3[cur]) if cur and cur in data3.keys() and data3[cur] != 0 else "  —",
2553                            "  {}: {}{:.2f}".format(cur, "+" if data4[cur] > 0 else "", data4[cur]) if cur and cur in data4.keys() and data4[cur] != 0 else "  —",
2554                    )
2555
2556                # --- view "Payments" lines:
2557                info.append("| **Payments:**              | Deposit on broker account:    | Withdrawals:                 | Dividends income:    | Coupons income:        |\n")
2558                paymentsKeys = sorted(list(set(list(customStat["payIn"].keys()) + list(customStat["payOut"].keys()) + list(customStat["divs"].keys()) + list(customStat["coupons"].keys()))))
2559
2560                for key in paymentsKeys:
2561                    info.append(_InfoStr(customStat["payIn"], customStat["payOut"], customStat["divs"], customStat["coupons"], key))
2562
2563                info.append(splitLine1)
2564
2565                # --- view "Commissions and taxes" lines:
2566                info.append("| **Commissions and taxes:** | Broker commissions:           | Service commissions:         | Margin commissions:  | All taxes/corrections: |\n")
2567                comKeys = sorted(list(set(list(customStat["brokerCom"].keys()) + list(customStat["serviceCom"].keys()) + list(customStat["marginCom"].keys()) + list(customStat["allTaxes"].keys()))))
2568
2569                for key in comKeys:
2570                    info.append(_InfoStr(customStat["brokerCom"], customStat["serviceCom"], customStat["marginCom"], customStat["allTaxes"], key))
2571
2572                info.append(splitLine1)
2573
2574                info.extend([
2575                    "\n## All operations{}\n\n".format("" if showCancelled else " (without cancelled status)"),
2576                    "| Date and time       | FIGI         | Ticker       | Asset      | Value     | Payment         | Status     | Operation type                                                     |\n",
2577                    "|---------------------|--------------|--------------|------------|-----------|-----------------|------------|--------------------------------------------------------------------|\n",
2578                ])
2579
2580            else:
2581                info.append("Broker returned no operations during this period\n")
2582
2583            # --- view "Operations" section:
2584            for item in ops:
2585                if not showCancelled and TKS_OPERATION_STATES[item["state"]] == TKS_OPERATION_STATES["OPERATION_STATE_CANCELED"]:
2586                    continue
2587
2588                else:
2589                    self.figi = item["figi"] if item["figi"] else ""
2590                    payment = NanoToFloat(item["payment"]["units"], item["payment"]["nano"])
2591                    instrument = self.SearchByFIGI(requestPrice=False) if self.figi else {}
2592
2593                    # group of deals during one day:
2594                    if nextDay and item["date"].split("T")[0] != nextDay:
2595                        info.append(splitLine2)
2596                        nextDay = ""
2597
2598                    else:
2599                        nextDay = item["date"].split("T")[0]  # saving current day for splitting
2600
2601                    info.append("| {:<19} | {:<12} | {:<12} | {:<10} | {:<9} | {:>15} | {:<10} | {:<66} |\n".format(
2602                        item["date"].replace("T", " ").replace("Z", "").split(".")[0],
2603                        self.figi if self.figi else "—",
2604                        instrument["ticker"] if instrument else "—",
2605                        instrument["type"] if instrument else "—",
2606                        item["quantity"] if int(item["quantity"]) > 0 else "—",
2607                        "{}{:.2f} {}".format("+" if payment > 0 else "", payment, item["payment"]["currency"]) if payment != 0 else "—",
2608                        TKS_OPERATION_STATES[item["state"]],
2609                        TKS_OPERATION_TYPES[item["operationType"]],
2610                    ))
2611
2612            infoText = "".join(info)
2613
2614            if show:
2615                if self.moreDebug:
2616                    uLogger.debug("Records about history of a client's operations successfully received")
2617
2618                uLogger.info(infoText)
2619
2620            if self.reportFile:
2621                with open(self.reportFile, "w", encoding="UTF-8") as fH:
2622                    fH.write(infoText)
2623
2624                uLogger.info("History of a client's operations are saved to file: [{}]".format(os.path.abspath(self.reportFile)))
2625
2626        return ops, customStat
2627
2628    def History(self, start: str = None, end: str = None, interval: str = "hour", onlyMissing: bool = False, csvSep: str = ",", show: bool = False) -> pd.DataFrame:
2629        """
2630        This method returns last history candles of the current instrument defined by `ticker` or `figi` (FIGI id).
2631
2632        History returned between two given dates: `start` and `end`. Minimum requested date in the past is `1970-01-01`.
2633        Warning! Broker server used ISO UTC time by default.
2634
2635        If `historyFile` is not `None` then method save history to file, otherwise return only Pandas DataFrame.
2636        Also, `historyFile` used to update history with `onlyMissing` parameter.
2637
2638        See also: `LoadHistory()` and `ShowHistoryChart()` methods.
2639
2640        :param start: see docstring in `GetDatesAsString()` method.
2641        :param end: see docstring in `GetDatesAsString()` method.
2642        :param interval: this is a candle interval. Current available values are `"1min"`, `"5min"`, `"15min"`,
2643                         `"hour"`, `"day"`. Default: `"hour"`.
2644        :param onlyMissing: if `True` then add only last missing candles, do not request all history length from `start`.
2645                            False by default. Warning! History appends only from last candle to current time
2646                            with always update last candle!
2647        :param csvSep: separator if csv-file is used, `,` by default.
2648        :param show: if `True` then also prints Pandas DataFrame to the console.
2649        :return: Pandas DataFrame with prices history. Headers of columns are defined by default:
2650                 `["date", "time", "open", "high", "low", "close", "volume"]`.
2651        """
2652        strStartDate, strEndDate = GetDatesAsString(start, end)  # example: ("2020-01-01T00:00:00Z", "2022-12-31T23:59:59Z")
2653        headers = ["date", "time", "open", "high", "low", "close", "volume"]  # sequence and names of column headers
2654        history = None  # empty pandas object for history
2655
2656        if interval not in TKS_CANDLE_INTERVALS.keys():
2657            uLogger.error("Interval parameter must be string with current available values: `1min`, `5min`, `15min`, `hour` and `day`.")
2658            raise Exception("Incorrect value")
2659
2660        if not (self.ticker or self.figi):
2661            uLogger.error("Ticker or FIGI must be defined!")
2662            raise Exception("Ticker or FIGI required")
2663
2664        if self.ticker and not self.figi:
2665            instrumentByTicker = self.SearchByTicker(requestPrice=False)
2666            self.figi = instrumentByTicker["figi"] if instrumentByTicker else ""
2667
2668        if self.figi and not self.ticker:
2669            instrumentByFIGI = self.SearchByFIGI(requestPrice=False)
2670            self.ticker = instrumentByFIGI["ticker"] if instrumentByFIGI else ""
2671
2672        dtStart = datetime.strptime(strStartDate, TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc())  # datetime object from start time string
2673        dtEnd = datetime.strptime(strEndDate, TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc())  # datetime object from end time string
2674        if interval.lower() != "day":
2675            dtEnd += timedelta(seconds=1)  # adds 1 sec for requests, because day end returned by `GetDatesAsString()` as 23:59:59
2676
2677        delta = dtEnd - dtStart  # current UTC time minus last time in file
2678        deltaMinutes = delta.days * 1440 + delta.seconds // 60  # minutes between start and end dates
2679
2680        # calculate history length in candles:
2681        length = deltaMinutes // TKS_CANDLE_INTERVALS[interval][1]
2682        if deltaMinutes % TKS_CANDLE_INTERVALS[interval][1] > 0:
2683            length += 1  # to avoid fraction time
2684
2685        # calculate data blocks count:
2686        blocks = 1 if length < TKS_CANDLE_INTERVALS[interval][2] else 1 + length // TKS_CANDLE_INTERVALS[interval][2]
2687
2688        uLogger.debug("Original requested time period in local time: from [{}] to [{}]".format(start, end))
2689        uLogger.debug("Requested time period is about from [{}] UTC to [{}] UTC".format(strStartDate, strEndDate))
2690        uLogger.debug("Calculated history length: [{}], interval: [{}]".format(length, interval))
2691        uLogger.debug("Data blocks, count: [{}], max candles in block: [{}]".format(blocks, TKS_CANDLE_INTERVALS[interval][2]))
2692        uLogger.debug("Requesting history candlesticks, ticker: [{}], FIGI: [{}]. Wait, please...".format(self.ticker, self.figi))
2693
2694        tempOld = None  # pandas object for old history, if --only-missing key present
2695        lastTime = None  # datetime object of last old candle in file
2696
2697        if onlyMissing and self.historyFile is not None and self.historyFile and os.path.exists(self.historyFile):
2698            uLogger.debug("--only-missing key present, add only last missing candles...")
2699            uLogger.debug("History file will be updated: [{}]".format(os.path.abspath(self.historyFile)))
2700
2701            tempOld = pd.read_csv(self.historyFile, sep=csvSep, header=None, names=headers)
2702
2703            tempOld["date"] = pd.to_datetime(tempOld["date"])  # load date "as is"
2704            tempOld["date"] = tempOld["date"].dt.strftime("%Y.%m.%d")  # convert date to string
2705            tempOld["time"] = pd.to_datetime(tempOld["time"])  # load time "as is"
2706            tempOld["time"] = tempOld["time"].dt.strftime("%H:%M")  # convert time to string
2707
2708            # get last datetime object from last string in file or minus 1 delta if file is empty:
2709            if len(tempOld) > 0:
2710                lastTime = datetime.strptime(tempOld.date.iloc[-1] + " " + tempOld.time.iloc[-1], "%Y.%m.%d %H:%M").replace(tzinfo=tzutc())
2711
2712            else:
2713                lastTime = dtEnd - timedelta(days=1)  # history file is empty, so last date set at -1 day
2714
2715            tempOld = tempOld[:-1]  # always remove last old candle because it may be incompletely at the current time
2716
2717        responseJSONs = []  # raw history blocks of data
2718
2719        blockEnd = dtEnd
2720        for item in range(blocks):
2721            tail = length % TKS_CANDLE_INTERVALS[interval][2] if item + 1 == blocks else TKS_CANDLE_INTERVALS[interval][2]
2722            blockStart = blockEnd - timedelta(minutes=TKS_CANDLE_INTERVALS[interval][1] * tail)
2723
2724            uLogger.debug("[Block #{}/{}] time period: [{}] UTC - [{}] UTC".format(
2725                item + 1, blocks, blockStart.strftime(TKS_DATE_TIME_FORMAT), blockEnd.strftime(TKS_DATE_TIME_FORMAT),
2726            ))
2727
2728            if blockStart == blockEnd:
2729                uLogger.debug("Skipped this zero-length block...")
2730
2731            else:
2732                # REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/MarketDataService/MarketDataService_GetCandles
2733                historyURL = self.server + r"/tinkoff.public.invest.api.contract.v1.MarketDataService/GetCandles"
2734                self.body = str({
2735                    "figi": self.figi,
2736                    "from": blockStart.strftime(TKS_DATE_TIME_FORMAT),
2737                    "to": blockEnd.strftime(TKS_DATE_TIME_FORMAT),
2738                    "interval": TKS_CANDLE_INTERVALS[interval][0]
2739                })
2740                responseJSON = self.SendAPIRequest(historyURL, reqType="POST", retry=1, pause=1)
2741
2742                if "code" in responseJSON.keys():
2743                    uLogger.debug("An issue occurred and block #{}/{} is empty".format(item + 1, blocks))
2744
2745                else:
2746                    if start is not None and (start.lower() == "yesterday" or start == end) and interval == "day" and len(responseJSON["candles"]) > 1:
2747                        responseJSON["candles"] = responseJSON["candles"][:-1]  # removes last candle for "yesterday" request
2748
2749                    responseJSONs = responseJSON["candles"] + responseJSONs  # add more old history behind newest dates
2750
2751            blockEnd = blockStart
2752
2753        printCount = len(responseJSONs)  # candles to show in console
2754        if responseJSONs:
2755            tempHistory = pd.DataFrame(
2756                data={
2757                    "date": [pd.to_datetime(item["time"]).astimezone(tzutc()) for item in responseJSONs],
2758                    "time": [pd.to_datetime(item["time"]).astimezone(tzutc()) for item in responseJSONs],
2759                    "open": [NanoToFloat(item["open"]["units"], item["open"]["nano"]) for item in responseJSONs],
2760                    "high": [NanoToFloat(item["high"]["units"], item["high"]["nano"]) for item in responseJSONs],
2761                    "low": [NanoToFloat(item["low"]["units"], item["low"]["nano"]) for item in responseJSONs],
2762                    "close": [NanoToFloat(item["close"]["units"], item["close"]["nano"]) for item in responseJSONs],
2763                    "volume": [int(item["volume"]) for item in responseJSONs],
2764                },
2765                index=range(len(responseJSONs)),
2766                columns=["date", "time", "open", "high", "low", "close", "volume"],
2767            )
2768            tempHistory["date"] = tempHistory["date"].dt.strftime("%Y.%m.%d")
2769            tempHistory["time"] = tempHistory["time"].dt.strftime("%H:%M")
2770
2771            # append only newest candles to old history if --only-missing key present:
2772            if onlyMissing and tempOld is not None and lastTime is not None:
2773                index = 0  # find start index in tempHistory data:
2774
2775                for i, item in tempHistory.iterrows():
2776                    curTime = datetime.strptime(item["date"] + " " + item["time"], "%Y.%m.%d %H:%M").replace(tzinfo=tzutc())
2777
2778                    if curTime == lastTime:
2779                        uLogger.debug("History will be updated starting from the date: [{}]".format(curTime.strftime(TKS_PRINT_DATE_TIME_FORMAT)))
2780                        index = i
2781                        printCount = index + 1
2782                        break
2783
2784                history = pd.concat([tempOld, tempHistory[index:]], ignore_index=True)
2785
2786            else:
2787                history = tempHistory  # if no `--only-missing` key then load full data from server
2788
2789            uLogger.debug("Last 3 rows of received history:\n{}".format(pd.DataFrame.to_string(history[["date", "time", "open", "high", "low", "close", "volume"]][-3:], max_cols=20, index=False)))
2790
2791        if history is not None and not history.empty:
2792            if show:
2793                uLogger.info("Here's requested history between [{}] UTC and [{}] UTC, not-empty candles count: [{}]\n{}".format(
2794                    strStartDate.replace("T", " ").replace("Z", ""), strEndDate.replace("T", " ").replace("Z", ""), len(history[-printCount:]),
2795                    pd.DataFrame.to_string(history[["date", "time", "open", "high", "low", "close", "volume"]][-printCount:], max_cols=20, index=False),
2796                ))
2797
2798        else:
2799            uLogger.warning("Received an empty candles history!")
2800
2801        if self.historyFile is not None:
2802            if history is not None and not history.empty:
2803                history.to_csv(self.historyFile, sep=csvSep, index=False, header=None)
2804                uLogger.info("Ticker [{}], FIGI [{}], tf: [{}], history saved: [{}]".format(self.ticker, self.figi, interval, os.path.abspath(self.historyFile)))
2805
2806            else:
2807                uLogger.warning("Empty history received! File NOT updated: [{}]".format(os.path.abspath(self.historyFile)))
2808
2809        else:
2810            uLogger.debug("--output key is not defined. Parsed history file not saved to file, only Pandas DataFrame returns.")
2811
2812        return history
2813
2814    def LoadHistory(self, filePath: str) -> pd.DataFrame:
2815        """
2816        Load candles history from csv-file and return Pandas DataFrame object.
2817
2818        See also: `History()` and `ShowHistoryChart()` methods.
2819
2820        :param filePath: path to csv-file to open.
2821        """
2822        loadedHistory = None  # init candles data object
2823
2824        uLogger.debug("Loading candles history with PriceGenerator module. Wait, please...")
2825
2826        if os.path.exists(filePath):
2827            loadedHistory = self.priceModel.LoadFromFile(filePath)  # load data and get chain of candles as Pandas DataFrame
2828
2829            tfStr = self.priceModel.FormattedDelta(
2830                self.priceModel.timeframe,
2831                "{days} days {hours}h {minutes}m {seconds}s",
2832            ) if self.priceModel.timeframe >= timedelta(days=1) else self.priceModel.FormattedDelta(
2833                self.priceModel.timeframe,
2834                "{hours}h {minutes}m {seconds}s",
2835            )
2836
2837            if loadedHistory is not None and not loadedHistory.empty:
2838                uLogger.info("Rows count loaded: [{}], detected timeframe of candles: [{}]. Showing some last rows:\n{}".format(
2839                    len(loadedHistory),
2840                    tfStr,
2841                    pd.DataFrame.to_string(loadedHistory[-10:], max_cols=20)),
2842                )
2843
2844            else:
2845                uLogger.warning("It was loaded an empty history! Path: [{}]".format(os.path.abspath(filePath)))
2846
2847        else:
2848            uLogger.error("File with candles history does not exist! Check the path: [{}]".format(filePath))
2849
2850        return loadedHistory
2851
2852    def ShowHistoryChart(self, candles: Union[str, pd.DataFrame] = None, interact: bool = True, openInBrowser: bool = False) -> None:
2853        """
2854        Render an HTML-file with interact or non-interact candlesticks chart. Candles may be path to the csv-file.
2855
2856        Self variable `htmlHistoryFile` can be use as html-file name to save interaction or non-interaction chart.
2857        Default: `index.html` (both for interact and non-interact candlesticks chart).
2858
2859        See also: `History()` and `LoadHistory()` methods.
2860
2861        :param candles: string to csv-file with candles in OHLCV-model or like Pandas Dataframe object.
2862        :param interact: if True (default) then chain of candlesticks will render as interactive Bokeh chart.
2863                         See examples: https://github.com/Tim55667757/PriceGenerator#overriding-parameters
2864                         If False then chain of candlesticks will render as not interactive Google Candlestick chart.
2865                         See examples: https://github.com/Tim55667757/PriceGenerator#statistics-and-chart-on-a-simple-template
2866        :param openInBrowser: if True then immediately open chart in default browser, otherwise only path to
2867                              html-file prints to console. False by default, to avoid issues with `permissions denied` to html-file.
2868        """
2869        if isinstance(candles, str):
2870            self.priceModel.prices = self.LoadHistory(filePath=candles)  # load candles chain from file
2871            self.priceModel.ticker = os.path.basename(candles)  # use filename as ticker name in PriceGenerator
2872
2873        elif isinstance(candles, pd.DataFrame):
2874            self.priceModel.prices = candles  # set candles chain from variable
2875            self.priceModel.ticker = self.ticker  # use current TKSBrokerAPI ticker as ticker name in PriceGenerator
2876
2877            if "datetime" not in candles.columns:
2878                self.priceModel.prices["datetime"] = pd.to_datetime(candles.date + ' ' + candles.time, utc=True)  # PriceGenerator uses "datetime" column with date and time
2879
2880        else:
2881            uLogger.error("`candles` variable must be path string to the csv-file with candles in OHLCV-model or like Pandas Dataframe object!")
2882            raise Exception("Incorrect value")
2883
2884        self.priceModel.horizon = len(self.priceModel.prices)  # use length of candles data as horizon in PriceGenerator
2885
2886        if interact:
2887            uLogger.debug("Rendering interactive candles chart. Wait, please...")
2888
2889            self.priceModel.RenderBokeh(fileName=self.htmlHistoryFile, viewInBrowser=openInBrowser)
2890
2891        else:
2892            uLogger.debug("Rendering non-interactive candles chart. Wait, please...")
2893
2894            self.priceModel.RenderGoogle(fileName=self.htmlHistoryFile, viewInBrowser=openInBrowser)
2895
2896        uLogger.info("Rendered candles chart: [{}]".format(os.path.abspath(self.htmlHistoryFile)))
2897
2898    def Trade(self, operation: str, lots: int = 1, tp: float = 0., sl: float = 0., expDate: str = "Undefined") -> dict:
2899        """
2900        Universal method to create market order and make deal at the current price for current `accountId`. Returns JSON data with response.
2901        If `tp` or `sl` > 0, then in additional will open stop-orders with "TP" and "SL" flags for `stopType` parameter.
2902
2903        See also: `Order()` docstring. More simple methods than `Trade()` are `Buy()` and `Sell()`.
2904
2905        :param operation: string "Buy" or "Sell".
2906        :param lots: volume, integer count of lots >= 1.
2907        :param tp: float > 0, target price for stop-order with "TP" type. It used as take profit parameter `targetPrice` in `self.Order()`.
2908        :param sl: float > 0, target price for stop-order with "SL" type. It used as stop loss parameter `targetPrice` in `self.Order()`.
2909        :param expDate: string "Undefined" by default or local date in future,
2910                        it is a string with format `%Y-%m-%d %H:%M:%S`.
2911        :return: JSON with response from broker server.
2912        """
2913        if self.accountId is None or not self.accountId:
2914            uLogger.error("Variable `accountId` must be defined for using this method!")
2915            raise Exception("Account ID required")
2916
2917        if operation is None or not operation or operation not in ("Buy", "Sell"):
2918            uLogger.error("You must define operation type only one of them: `Buy` or `Sell`!")
2919            raise Exception("Incorrect value")
2920
2921        if lots is None or lots < 1:
2922            uLogger.warning("You must define trade volume > 0: integer count of lots! For current operation lots reset to 1.")
2923            lots = 1
2924
2925        if tp is None or tp < 0:
2926            tp = 0
2927
2928        if sl is None or sl < 0:
2929            sl = 0
2930
2931        if expDate is None or not expDate:
2932            expDate = "Undefined"
2933
2934        if not (self.ticker or self.figi):
2935            uLogger.error("Ticker or FIGI must be defined!")
2936            raise Exception("Ticker or FIGI required")
2937
2938        instrument = self.SearchByTicker(requestPrice=True) if self.ticker else self.SearchByFIGI(requestPrice=True)
2939        self.ticker = instrument["ticker"]
2940        self.figi = instrument["figi"]
2941
2942        uLogger.debug("Opening [{}] market order: ticker [{}], FIGI [{}], lots [{}], TP [{:.4f}], SL [{:.4f}], expiration date of TP/SL orders [{}]. Wait, please...".format(operation, self.ticker, self.figi, lots, tp, sl, expDate))
2943
2944        openTradeURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OrdersService/PostOrder"
2945        self.body = str({
2946            "figi": self.figi,
2947            "quantity": str(lots),
2948            "direction": "ORDER_DIRECTION_BUY" if operation == "Buy" else "ORDER_DIRECTION_SELL",  # see: TKS_ORDER_DIRECTIONS
2949            "accountId": str(self.accountId),
2950            "orderType": "ORDER_TYPE_MARKET",  # see: TKS_ORDER_TYPES
2951        })
2952        response = self.SendAPIRequest(openTradeURL, reqType="POST", retry=0)
2953
2954        if "orderId" in response.keys():
2955            uLogger.info("[{}] market order [{}] was executed: ticker [{}], FIGI [{}], lots [{}]. Total order price: [{:.4f} {}] (with commission: [{:.2f} {}]). Average price of lot: [{:.2f} {}]".format(
2956                operation, response["orderId"],
2957                self.ticker, self.figi, lots,
2958                NanoToFloat(response["totalOrderAmount"]["units"], response["totalOrderAmount"]["nano"]), response["totalOrderAmount"]["currency"],
2959                NanoToFloat(response["initialCommission"]["units"], response["initialCommission"]["nano"]), response["initialCommission"]["currency"],
2960                NanoToFloat(response["executedOrderPrice"]["units"], response["executedOrderPrice"]["nano"]), response["executedOrderPrice"]["currency"],
2961            ))
2962
2963        else:
2964            uLogger.warning("Not `oK` status received! Market order not executed. See full debug log or try again and open order later.")
2965
2966        if tp > 0:
2967            self.Order(operation="Sell" if operation == "Buy" else "Buy", orderType="Stop", lots=lots, targetPrice=tp, limitPrice=tp, stopType="TP", expDate=expDate)
2968
2969        if sl > 0:
2970            self.Order(operation="Sell" if operation == "Buy" else "Buy", orderType="Stop", lots=lots, targetPrice=sl, limitPrice=sl, stopType="SL", expDate=expDate)
2971
2972        return response
2973
2974    def Buy(self, lots: int = 1, tp: float = 0., sl: float = 0., expDate: str = "Undefined") -> dict:
2975        """
2976        More simple method than `Trade()`. Create `Buy` market order and make deal at the current price. Returns JSON data with response.
2977        If `tp` or `sl` > 0, then in additional will opens stop-orders with "TP" and "SL" flags for `stopType` parameter.
2978
2979        See also: `Order()` and `Trade()` docstrings.
2980
2981        :param lots: volume, integer count of lots >= 1.
2982        :param tp: float > 0, take profit price of stop-order.
2983        :param sl: float > 0, stop loss price of stop-order.
2984        :param expDate: it's a local date in future.
2985                        String has a format like this: `%Y-%m-%d %H:%M:%S`.
2986        :return: JSON with response from broker server.
2987        """
2988        return self.Trade(operation="Buy", lots=lots, tp=tp, sl=sl, expDate=expDate)
2989
2990    def Sell(self, lots: int = 1, tp: float = 0., sl: float = 0., expDate: str = "Undefined") -> dict:
2991        """
2992        More simple method than `Trade()`. Create `Sell` market order and make deal at the current price. Returns JSON data with response.
2993        If `tp` or `sl` > 0, then in additional will open stop-orders with "TP" and "SL" flags for `stopType` parameter.
2994
2995        See also: `Order()` and `Trade()` docstrings.
2996
2997        :param lots: volume, integer count of lots >= 1.
2998        :param tp: float > 0, take profit price of stop-order.
2999        :param sl: float > 0, stop loss price of stop-order.
3000        :param expDate: it's a local date in the future.
3001                        String has a format like this: `%Y-%m-%d %H:%M:%S`.
3002        :return: JSON with response from broker server.
3003        """
3004        return self.Trade(operation="Sell", lots=lots, tp=tp, sl=sl, expDate=expDate)
3005
3006    def CloseTrades(self, instruments: list[str], portfolio: dict = None) -> None:
3007        """
3008        Close position of given instruments.
3009
3010        :param instruments: list of instruments defined by tickers or FIGIs that must be closed.
3011        :param portfolio: pre-received dictionary with open trades, returned by `Overview()` method.
3012                         This avoids unnecessary downloading data from the server.
3013        """
3014        if instruments is None or not instruments:
3015            uLogger.error("List of tickers or FIGIs must be defined for using this method!")
3016            raise Exception("Ticker or FIGI required")
3017
3018        if isinstance(instruments, str):
3019            instruments = [instruments]
3020
3021        uniqueInstruments = self.GetUniqueFIGIs(instruments)
3022        if uniqueInstruments:
3023            if portfolio is None or not portfolio:
3024                portfolio = self.Overview(show=False)
3025
3026            allOpened = [item["figi"] for iType in TKS_INSTRUMENTS for item in portfolio["stat"][iType]]
3027            uLogger.debug("All opened instruments by it's FIGI: {}".format(", ".join(allOpened)))
3028
3029            for self.figi in uniqueInstruments:
3030                if self.figi not in allOpened:
3031                    uLogger.warning("Instrument with FIGI [{}] not in open positions list!".format(self.figi))
3032                    continue
3033
3034                # search open trade info about instrument by ticker:
3035                instrument = {}
3036                for iType in TKS_INSTRUMENTS:
3037                    if instrument:
3038                        break
3039
3040                    for item in portfolio["stat"][iType]:
3041                        if item["figi"] == self.figi:
3042                            instrument = item
3043                            break
3044
3045                if instrument:
3046                    self.ticker = instrument["ticker"]
3047                    self.figi = instrument["figi"]
3048
3049                    uLogger.debug("Closing trade of instrument: ticker [{}], FIGI[{}], lots [{}]{}. Wait, please...".format(
3050                        self.ticker,
3051                        self.figi,
3052                        int(instrument["volume"]),
3053                        ", blocked [{}]".format(instrument["blocked"]) if instrument["blocked"] > 0 else "",
3054                    ))
3055
3056                    tradeLots = abs(instrument["lots"]) - instrument["blocked"]  # available volumes in lots for close operation
3057
3058                    if tradeLots > 0:
3059                        if instrument["blocked"] > 0:
3060                            uLogger.warning("Just for your information: there are [{}] lots blocked for instrument [{}]! Available only [{}] lots to closing trade.".format(
3061                                instrument["blocked"],
3062                                self.ticker,
3063                                tradeLots,
3064                            ))
3065
3066                        # if direction is "Long" then we need sell, if direction is "Short" then we need buy:
3067                        self.Trade(operation="Sell" if instrument["direction"] == "Long" else "Buy", lots=tradeLots)
3068
3069                    else:
3070                        uLogger.warning("There are no available lots for instrument [{}] to closing trade at this moment! Try again later or cancel some orders.".format(self.ticker))
3071
3072    def CloseAllTrades(self, iType: str, portfolio: dict = None) -> None:
3073        """
3074        Close all positions of given instruments with defined type.
3075
3076        :param iType: type of the instruments that be closed, it must be one of supported types in TKS_INSTRUMENTS list.
3077        :param portfolio: pre-received dictionary with open trades, returned by `Overview()` method.
3078                         This avoids unnecessary downloading data from the server.
3079        """
3080        if iType not in TKS_INSTRUMENTS:
3081            uLogger.warning("Type of the instrument must be one of supported types: {}. Given: [{}]".format(", ".join(TKS_INSTRUMENTS), iType))
3082
3083        else:
3084            if portfolio is None or not portfolio:
3085                portfolio = self.Overview(show=False)
3086
3087            tickers = [item["ticker"] for item in portfolio["stat"][iType]]
3088            uLogger.debug("Instrument tickers with type [{}] that will be closed: {}".format(iType, tickers))
3089
3090            if tickers and portfolio:
3091                self.CloseTrades(tickers, portfolio)
3092
3093            else:
3094                uLogger.info("Instrument tickers with type [{}] not found, nothing to close.".format(iType))
3095
3096    def Order(self, operation: str, orderType: str, lots: int, targetPrice: float, limitPrice: float = 0., stopType: str = "Limit", expDate: str = "Undefined") -> dict:
3097        """
3098        Universal method to create market or limit orders with all available parameters for current `accountId`.
3099        See more simple methods: `BuyLimit()`, `BuyStop()`, `SellLimit()`, `SellStop()`.
3100
3101        If orderType is "Limit" then create pending limit-order below current price if operation is "Buy" and above
3102        current price if operation is "Sell". A limit order has no expiration date, it lasts until the end of the trading day.
3103
3104        Warning! If you try to create limit-order above current price if "Buy" or below current price if "Sell"
3105        then broker immediately open market order as you can do simple --buy or --sell operations!
3106
3107        If orderType is "Stop" then creates stop-order with any direction "Buy" or "Sell".
3108        When current price will go up or down to target price value then broker opens a limit order.
3109        Stop-order is opened with unlimited expiration date by default, or you can define expiration date with expDate parameter.
3110
3111        Only one attempt and no retry for opens order. If network issue occurred you can create new request.
3112
3113        :param operation: string "Buy" or "Sell".
3114        :param orderType: string "Limit" or "Stop".
3115        :param lots: volume, integer count of lots >= 1.
3116        :param targetPrice: target price > 0. This is open trade price for limit order.
3117        :param limitPrice: limit price >= 0. This parameter only makes sense for stop-order. If limitPrice = 0, then it set as targetPrice.
3118                           Broker will creates limit-order with price equal to limitPrice, when current price goes to target price of stop-order.
3119        :param stopType: string "Limit" by default. This parameter only makes sense for stop-order. There are 3 stop-order types
3120                         "SL", "TP", "Limit" for "Stop loss", "Take profit" and "Stop limit" types accordingly.
3121                         Stop loss order always executed by market price.
3122        :param expDate: string "Undefined" by default or local date in future.
3123                        String has a format like this: `%Y-%m-%d %H:%M:%S`.
3124                        This date is converting to UTC format for server. This parameter only makes sense for stop-order.
3125                        A limit order has no expiration date, it lasts until the end of the trading day.
3126        :return: JSON with response from broker server.
3127        """
3128        if self.accountId is None or not self.accountId:
3129            uLogger.error("Variable `accountId` must be defined for using this method!")
3130            raise Exception("Account ID required")
3131
3132        if operation is None or not operation or operation not in ("Buy", "Sell"):
3133            uLogger.error("You must define operation type only one of them: `Buy` or `Sell`!")
3134            raise Exception("Incorrect value")
3135
3136        if orderType is None or not orderType or orderType not in ("Limit", "Stop"):
3137            uLogger.error("You must define order type only one of them: `Limit` or `Stop`!")
3138            raise Exception("Incorrect value")
3139
3140        if lots is None or lots < 1:
3141            uLogger.error("You must define trade volume > 0: integer count of lots!")
3142            raise Exception("Incorrect value")
3143
3144        if targetPrice is None or targetPrice <= 0:
3145            uLogger.error("Target price for limit-order must be greater than 0!")
3146            raise Exception("Incorrect value")
3147
3148        if limitPrice is None or limitPrice <= 0:
3149            limitPrice = targetPrice
3150
3151        if stopType is None or not stopType or stopType not in ("SL", "TP", "Limit"):
3152            stopType = "Limit"
3153
3154        if expDate is None or not expDate:
3155            expDate = "Undefined"
3156
3157        if not (self.ticker or self.figi):
3158            uLogger.error("Tocker or FIGI must be defined!")
3159            raise Exception("Ticker or FIGI required")
3160
3161        response = {}
3162        instrument = self.SearchByTicker(requestPrice=True) if self.ticker else self.SearchByFIGI(requestPrice=True)
3163        self.ticker = instrument["ticker"]
3164        self.figi = instrument["figi"]
3165
3166        if orderType == "Limit":
3167            uLogger.debug(
3168                "Creating pending limit-order: ticker [{}], FIGI [{}], action [{}], lots [{}] and the target price [{:.2f} {}]. Wait, please...".format(
3169                    self.ticker, self.figi,
3170                    operation, lots, targetPrice, instrument["currency"],
3171                ))
3172
3173            openOrderURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OrdersService/PostOrder"
3174            self.body = str({
3175                "figi": self.figi,
3176                "quantity": str(lots),
3177                "price": FloatToNano(targetPrice),
3178                "direction": "ORDER_DIRECTION_BUY" if operation == "Buy" else "ORDER_DIRECTION_SELL",  # see: TKS_ORDER_DIRECTIONS
3179                "accountId": str(self.accountId),
3180                "orderType": "ORDER_TYPE_LIMIT",  # see: TKS_ORDER_TYPES
3181            })
3182            response = self.SendAPIRequest(openOrderURL, reqType="POST", retry=0)
3183
3184            if "orderId" in response.keys():
3185                uLogger.info(
3186                    "Limit-order [{}] was created: ticker [{}], FIGI [{}], action [{}], lots [{}], target price [{:.2f} {}]".format(
3187                        response["orderId"],
3188                        self.ticker, self.figi,
3189                        operation, lots, targetPrice, instrument["currency"],
3190                    ))
3191
3192                if "lastPrice" in instrument["currentPrice"].keys() and instrument["currentPrice"]["lastPrice"]:
3193                    if operation == "Buy" and targetPrice > instrument["currentPrice"]["lastPrice"]:
3194                        uLogger.warning("Your order was executed as a market order, not as a limit order! Comment: because your target price [{:.2f} {}] was higher than current price [{:.2f} {}] broker immediately opened `Buy` market order, such as if you did simple `--buy` operation.".format(
3195                            targetPrice, instrument["currency"],
3196                            instrument["currentPrice"]["lastPrice"], instrument["currency"],
3197                        ))
3198
3199                    if operation == "Sell" and targetPrice < instrument["currentPrice"]["lastPrice"]:
3200                        uLogger.warning("Your order was executed as a market order, not as a limit order! Comment: because your target price [{:.2f} {}] was lower than current price [{:.2f} {}] broker immediately opened `Sell` market order, such as if you did simple `--sell` operation.".format(
3201                            targetPrice, instrument["currency"],
3202                            instrument["currentPrice"]["lastPrice"], instrument["currency"],
3203                        ))
3204
3205            else:
3206                uLogger.warning("Not `oK` status received! Limit order not opened. See full debug log or try again and open order later.")
3207
3208        if orderType == "Stop":
3209            uLogger.debug(
3210                "Creating stop-order: ticker [{}], FIGI [{}], action [{}], lots [{}], target price [{:.2f} {}], limit price [{:.2f} {}], stop-order type [{}] and local expiration date [{}]. Wait, please...".format(
3211                    self.ticker, self.figi,
3212                    operation, lots,
3213                    targetPrice, instrument["currency"],
3214                    limitPrice, instrument["currency"],
3215                    stopType, expDate,
3216                ))
3217
3218            openOrderURL = self.server + r"/tinkoff.public.invest.api.contract.v1.StopOrdersService/PostStopOrder"
3219            expDateUTC = "" if expDate == "Undefined" else datetime.strptime(expDate, TKS_PRINT_DATE_TIME_FORMAT).replace(tzinfo=tzlocal()).astimezone(tzutc()).strftime(TKS_DATE_TIME_FORMAT_EXT)
3220            stopOrderType = "STOP_ORDER_TYPE_STOP_LOSS" if stopType == "SL" else "STOP_ORDER_TYPE_TAKE_PROFIT" if stopType == "TP" else "STOP_ORDER_TYPE_STOP_LIMIT"
3221
3222            body = {
3223                "figi": self.figi,
3224                "quantity": str(lots),
3225                "price": FloatToNano(limitPrice),
3226                "stopPrice": FloatToNano(targetPrice),
3227                "direction": "STOP_ORDER_DIRECTION_BUY" if operation == "Buy" else "STOP_ORDER_DIRECTION_SELL",  # see: TKS_STOP_ORDER_DIRECTIONS
3228                "accountId": str(self.accountId),
3229                "expirationType": "STOP_ORDER_EXPIRATION_TYPE_GOOD_TILL_DATE" if expDateUTC else "STOP_ORDER_EXPIRATION_TYPE_GOOD_TILL_CANCEL",  # see: TKS_STOP_ORDER_EXPIRATION_TYPES
3230                "stopOrderType": stopOrderType,  # see: TKS_STOP_ORDER_TYPES
3231            }
3232
3233            if expDateUTC:
3234                body["expireDate"] = expDateUTC
3235
3236            self.body = str(body)
3237            response = self.SendAPIRequest(openOrderURL, reqType="POST", retry=0)
3238
3239            if "stopOrderId" in response.keys():
3240                uLogger.info(
3241                    "Stop-order [{}] was created: ticker [{}], FIGI [{}], action [{}], lots [{}], target price [{:.2f} {}], limit price [{:.2f} {}], stop-order type [{}] and expiration date in UTC [{}]".format(
3242                        response["stopOrderId"],
3243                        self.ticker, self.figi,
3244                        operation, lots,
3245                        targetPrice, instrument["currency"],
3246                        limitPrice, instrument["currency"],
3247                        TKS_STOP_ORDER_TYPES[stopOrderType],
3248                        datetime.strptime(expDateUTC, TKS_DATE_TIME_FORMAT_EXT).replace(tzinfo=tzutc()).astimezone(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT) if expDateUTC else TKS_STOP_ORDER_EXPIRATION_TYPES["STOP_ORDER_EXPIRATION_TYPE_UNSPECIFIED"],
3249                    ))
3250
3251                if "lastPrice" in instrument["currentPrice"].keys() and instrument["currentPrice"]["lastPrice"]:
3252                    if operation == "Buy" and targetPrice < instrument["currentPrice"]["lastPrice"] and stopType != "TP":
3253                        uLogger.warning("The broker will cancel this order after some time. Comment: you placed the wrong stop order because the target buy price [{:.2f} {}] is lower than the current price [{:.2f} {}]. Also try to set up order type as `TP` if you want to place stop order at that price.".format(
3254                            targetPrice, instrument["currency"],
3255                            instrument["currentPrice"]["lastPrice"], instrument["currency"],
3256                        ))
3257
3258                    if operation == "Sell" and targetPrice > instrument["currentPrice"]["lastPrice"] and stopType != "TP":
3259                        uLogger.warning("The broker will cancel this order after some time. Comment: you placed the wrong stop order because the target sell price [{:.2f} {}] is higher than the current price [{:.2f} {}]. Also try to set up order type as `TP` if you want to place stop order at that price.".format(
3260                            targetPrice, instrument["currency"],
3261                            instrument["currentPrice"]["lastPrice"], instrument["currency"],
3262                        ))
3263
3264            else:
3265                uLogger.warning("Not `oK` status received! Stop order not opened. See full debug log or try again and open order later.")
3266
3267        return response
3268
3269    def BuyLimit(self, lots: int, targetPrice: float) -> dict:
3270        """
3271        Create pending `Buy` limit-order (below current price). You must specify only 2 parameters:
3272        `lots` and `target price` to open buy limit-order. If you try to create buy limit-order above current price then
3273        broker immediately open `Buy` market order, such as if you do simple `--buy` operation!
3274        See also: `Order()` docstring.
3275
3276        :param lots: volume, integer count of lots >= 1.
3277        :param targetPrice: target price > 0. This is open trade price for limit order.
3278        :return: JSON with response from broker server.
3279        """
3280        return self.Order(operation="Buy", orderType="Limit", lots=lots, targetPrice=targetPrice)
3281
3282    def BuyStop(self, lots: int, targetPrice: float, limitPrice: float = 0., stopType: str = "Limit", expDate: str = "Undefined") -> dict:
3283        """
3284        Create `Buy` stop-order. You must specify at least 2 parameters: `lots` `target price` to open buy stop-order.
3285        In additional you can specify 3 parameters for buy stop-order: `limit price` >=0, `stop type` = Limit|SL|TP,
3286        `expiration date` = Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`. When current price will go up or down to
3287        target price value then broker opens a limit order. See also: `Order()` docstring.
3288
3289        :param lots: volume, integer count of lots >= 1.
3290        :param targetPrice: target price > 0. This is trigger price for buy stop-order.
3291        :param limitPrice: limit price >= 0 (limitPrice = targetPrice if limitPrice is 0). Broker will creates limit-order
3292                           with price equal to limitPrice, when current price goes to target price of buy stop-order.
3293        :param stopType: string "Limit" by default. There are 3 stop-order types "SL", "TP", "Limit"
3294                         for "Stop loss", "Take profit" and "Stop limit" types accordingly.
3295        :param expDate: string "Undefined" by default or local date in future.
3296                        String has a format like this: `%Y-%m-%d %H:%M:%S`.
3297                        This date is converting to UTC format for server.
3298        :return: JSON with response from broker server.
3299        """
3300        return self.Order(operation="Buy", orderType="Stop", lots=lots, targetPrice=targetPrice, limitPrice=limitPrice, stopType=stopType, expDate=expDate)
3301
3302    def SellLimit(self, lots: int, targetPrice: float) -> dict:
3303        """
3304        Create pending `Sell` limit-order (above current price). You must specify only 2 parameters:
3305        `lots` and `target price` to open sell limit-order. If you try to create sell limit-order below current price then
3306        broker immediately open `Sell` market order, such as if you do simple `--sell` operation!
3307        See also: `Order()` docstring.
3308
3309        :param lots: volume, integer count of lots >= 1.
3310        :param targetPrice: target price > 0. This is open trade price for limit order.
3311        :return: JSON with response from broker server.
3312        """
3313        return self.Order(operation="Sell", orderType="Limit", lots=lots, targetPrice=targetPrice)
3314
3315    def SellStop(self, lots: int, targetPrice: float, limitPrice: float = 0., stopType: str = "Limit", expDate: str = "Undefined") -> dict:
3316        """
3317        Create `Sell` stop-order. You must specify at least 2 parameters: `lots` `target price` to open sell stop-order.
3318        In additional you can specify 3 parameters for sell stop-order: `limit price` >=0, `stop type` = Limit|SL|TP,
3319        `expiration date` = Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`. When current price will go up or down to
3320        target price value then broker opens a limit order. See also: `Order()` docstring.
3321
3322        :param lots: volume, integer count of lots >= 1.
3323        :param targetPrice: target price > 0. This is trigger price for sell stop-order.
3324        :param limitPrice: limit price >= 0 (limitPrice = targetPrice if limitPrice is 0). Broker will creates limit-order
3325                           with price equal to limitPrice, when current price goes to target price of sell stop-order.
3326        :param stopType: string "Limit" by default. There are 3 stop-order types "SL", "TP", "Limit"
3327                         for "Stop loss", "Take profit" and "Stop limit" types accordingly.
3328        :param expDate: string "Undefined" by default or local date in future.
3329                        String has a format like this: `%Y-%m-%d %H:%M:%S`.
3330                        This date is converting to UTC format for server.
3331        :return: JSON with response from broker server.
3332        """
3333        return self.Order(operation="Sell", orderType="Stop", lots=lots, targetPrice=targetPrice, limitPrice=limitPrice, stopType=stopType, expDate=expDate)
3334
3335    def CloseOrders(self, orderIDs: list, allOrdersIDs: list = None, allStopOrdersIDs: list = None) -> None:
3336        """
3337        Cancel order or list of orders by its `orderId` or `stopOrderId` for current `accountId`.
3338
3339        :param orderIDs: list of integers with `orderId` or `stopOrderId`.
3340        :param allOrdersIDs: pre-received lists of all active pending orders.
3341                             This avoids unnecessary downloading data from the server.
3342        :param allStopOrdersIDs: pre-received lists of all active stop orders.
3343        """
3344        if self.accountId is None or not self.accountId:
3345            uLogger.error("Variable `accountId` must be defined for using this method!")
3346            raise Exception("Account ID required")
3347
3348        if orderIDs:
3349            if allOrdersIDs is None or not allOrdersIDs:
3350                rawOrders = self.RequestPendingOrders()
3351                allOrdersIDs = [item["orderId"] for item in rawOrders]  # all pending orders ID
3352
3353            if allStopOrdersIDs is None or not allStopOrdersIDs:
3354                rawStopOrders = self.RequestStopOrders()
3355                allStopOrdersIDs = [item["stopOrderId"] for item in rawStopOrders]  # all stop orders ID
3356
3357            for orderID in orderIDs:
3358                idInPendingOrders = orderID in allOrdersIDs
3359                idInStopOrders = orderID in allStopOrdersIDs
3360
3361                if not (idInPendingOrders or idInStopOrders):
3362                    uLogger.warning("Order not found by ID: [{}]. Maybe cancelled already? Check it with `--overview` key.".format(orderID))
3363                    continue
3364
3365                else:
3366                    if idInPendingOrders:
3367                        uLogger.debug("Cancelling pending order with ID: [{}]. Wait, please...".format(orderID))
3368
3369                        # REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/OrdersService/OrdersService_CancelOrder
3370                        self.body = str({"accountId": self.accountId, "orderId": orderID})
3371                        closeURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OrdersService/CancelOrder"
3372                        responseJSON = self.SendAPIRequest(closeURL, reqType="POST")
3373
3374                        if responseJSON and "time" in responseJSON.keys() and responseJSON["time"]:
3375                            if self.moreDebug:
3376                                uLogger.debug("Success time marker received from server: [{}] (UTC)".format(responseJSON["time"]))
3377
3378                            uLogger.info("Pending order with ID [{}] successfully cancel".format(orderID))
3379
3380                        else:
3381                            uLogger.warning("Unknown issue occurred when cancelling pending order with ID: [{}]. Check ID and try again.".format(orderID))
3382
3383                    elif idInStopOrders:
3384                        uLogger.debug("Cancelling stop order with ID: [{}]. Wait, please...".format(orderID))
3385
3386                        # REST API for request: https://tinkoff.github.io/investAPI/swagger-ui/#/StopOrdersService/StopOrdersService_CancelStopOrder
3387                        self.body = str({"accountId": self.accountId, "stopOrderId": orderID})
3388                        closeURL = self.server + r"/tinkoff.public.invest.api.contract.v1.StopOrdersService/CancelStopOrder"
3389                        responseJSON = self.SendAPIRequest(closeURL, reqType="POST")
3390
3391                        if responseJSON and "time" in responseJSON.keys() and responseJSON["time"]:
3392                            if self.moreDebug:
3393                                uLogger.debug("Success time marker received from server: [{}] (UTC)".format(responseJSON["time"]))
3394
3395                            uLogger.info("Stop order with ID [{}] successfully cancel".format(orderID))
3396
3397                        else:
3398                            uLogger.warning("Unknown issue occurred when cancelling stop order with ID: [{}]. Check ID and try again.".format(orderID))
3399
3400                    else:
3401                        continue
3402
3403    def CloseAllOrders(self) -> None:
3404        """
3405        Gets a list of open pending and stop orders and cancel it all.
3406        """
3407        rawOrders = self.RequestPendingOrders()
3408        allOrdersIDs = [item["orderId"] for item in rawOrders]  # all pending orders ID
3409        lenOrders = len(allOrdersIDs)
3410
3411        rawStopOrders = self.RequestStopOrders()
3412        allStopOrdersIDs = [item["stopOrderId"] for item in rawStopOrders]  # all stop orders ID
3413        lenSOrders = len(allStopOrdersIDs)
3414
3415        if lenOrders > 0 or lenSOrders > 0:
3416            uLogger.info("Found: [{}] opened pending and [{}] stop orders. Let's trying to cancel it all. Wait, please...".format(lenOrders, lenSOrders))
3417
3418            self.CloseOrders(allOrdersIDs + allStopOrdersIDs, allOrdersIDs, allStopOrdersIDs)
3419
3420        else:
3421            uLogger.info("Orders not found, nothing to cancel.")
3422
3423    def CloseAll(self, *args) -> None:
3424        """
3425        Close all available (not blocked) opened trades and orders.
3426
3427        Also, you can select one or more keywords case-insensitive:
3428        `orders`, `shares`, `bonds`, `etfs` and `futures` from `TKS_INSTRUMENTS` enum to specify trades type.
3429
3430        Currency positions you must close manually using buy or sell operations, `CloseTrades()` or `CloseAllTrades()` methods.
3431        """
3432        overview = self.Overview(show=False)  # get all open trades info
3433
3434        if len(args) == 0:
3435            uLogger.debug("Closing all available (not blocked) opened trades and orders. Currency positions you must closes manually using buy or sell operations! Wait, please...")
3436            self.CloseAllOrders()  # close all pending and stop orders
3437
3438            for iType in TKS_INSTRUMENTS:
3439                if iType != "Currencies":
3440                    self.CloseAllTrades(iType, overview)  # close all positions of instruments with same type without currencies
3441
3442        else:
3443            uLogger.debug("Closing all available {}. Currency positions you must closes manually using buy or sell operations! Wait, please...".format(list(args)))
3444            lowerArgs = [x.lower() for x in args]
3445
3446            if "orders" in lowerArgs:
3447                self.CloseAllOrders()  # close all pending and stop orders
3448
3449            for iType in TKS_INSTRUMENTS:
3450                if iType.lower() in lowerArgs and iType != "Currencies":
3451                    self.CloseAllTrades(iType, overview)  # close all positions of instruments with same type without currencies
3452
3453    @staticmethod
3454    def ParseOrderParameters(operation, **inputParameters):
3455        """
3456        Parse input dictionary of strings with order parameters and return dictionary with parameters to open all orders.
3457
3458        :param operation: string "Buy" or "Sell".
3459        :param inputParameters: this is dict of strings that looks like this
3460               `{"lots": "L_int,...", "prices": "P_float,..."}` where
3461               "lots" key: one or more lot values (integer numbers) to open with every limit-order
3462               "prices" key: one or more prices to open limit-orders
3463               Counts of values in lots and prices lists must be equals!
3464        :return: list of dictionaries with all lots and prices to open orders that looks like this `[{"lot": lots_1, "price": price_1}, {...}, ...]`
3465        """
3466        # TODO: update order grid work with api v2
3467        pass
3468        # uLogger.debug("Input parameters: {}".format(inputParameters))
3469        #
3470        # if operation is None or not operation or operation not in ("Buy", "Sell"):
3471        #     uLogger.error("You must define operation type: 'Buy' or 'Sell'!")
3472        #     raise Exception("Incorrect value")
3473        #
3474        # if "l" in inputParameters.keys():
3475        #     inputParameters["lots"] = inputParameters.pop("l")
3476        #
3477        # if "p" in inputParameters.keys():
3478        #     inputParameters["prices"] = inputParameters.pop("p")
3479        #
3480        # if "lots" not in inputParameters.keys() or "prices" not in inputParameters.keys():
3481        #     uLogger.error("Both of 'lots' and 'prices' keys must be define to open grid orders!")
3482        #     raise Exception("Incorrect value")
3483        #
3484        # lots = [int(item.strip()) for item in inputParameters["lots"].split(",")]
3485        # prices = [float(item.strip()) for item in inputParameters["prices"].split(",")]
3486        #
3487        # if len(lots) != len(prices):
3488        #     uLogger.error("'lots' and 'prices' lists must have equal length of values!")
3489        #     raise Exception("Incorrect value")
3490        #
3491        # uLogger.debug("Extracted parameters for orders:")
3492        # uLogger.debug("lots = {}".format(lots))
3493        # uLogger.debug("prices = {}".format(prices))
3494        #
3495        # # list of dictionaries with order's parameters: [{"lot": lots_1, "price": price_1}, {...}, ...]
3496        # result = [{"lot": lots[item], "price": prices[item]} for item in range(len(prices))]
3497        # uLogger.debug("Order parameters: {}".format(result))
3498        #
3499        # return result
3500
3501    def IsInPortfolio(self, portfolio: dict = None) -> bool:
3502        """
3503        Checks if instrument is in the user's portfolio. Instrument must be defined by `ticker` (highly priority) or `figi`.
3504
3505        :param portfolio: dict with user's portfolio data. If `None`, then requests portfolio from `Overview()` method.
3506        :return: `True` if portfolio contains open position with given instrument, `False` otherwise.
3507        """
3508        result = False
3509        msg = "Instrument not defined!"
3510
3511        if portfolio is None or not portfolio:
3512            portfolio = self.Overview(show=False)
3513
3514        if self.ticker:
3515            uLogger.debug("Searching instrument with ticker [{}] throwout opened positions...".format(self.ticker))
3516            msg = "Instrument with ticker [{}] is not present in open positions".format(self.ticker)
3517
3518            for iType in TKS_INSTRUMENTS:
3519                for instrument in portfolio["stat"][iType]:
3520                    if instrument["ticker"] == self.ticker:
3521                        result = True
3522                        msg = "Instrument with ticker [{}] is present in open positions".format(self.ticker)
3523                        break
3524
3525        elif self.figi:
3526            uLogger.debug("Searching instrument with FIGI [{}] throwout opened positions...".format(self.figi))
3527            msg = "Instrument with FIGI [{}] is not present in open positions".format(self.figi)
3528
3529            for iType in TKS_INSTRUMENTS:
3530                for instrument in portfolio["stat"][iType]:
3531                    if instrument["figi"] == self.figi:
3532                        result = True
3533                        msg = "Instrument with FIGI [{}] is present in open positions".format(self.figi)
3534                        break
3535
3536        else:
3537            uLogger.warning("Instrument must be defined by `ticker` (highly priority) or `figi`!")
3538
3539        uLogger.debug(msg)
3540
3541        return result
3542
3543    def GetInstrumentFromPortfolio(self, portfolio: dict = None) -> dict:
3544        """
3545        Returns instrument is in the user's portfolio if it presents there.
3546        Instrument must be defined by `ticker` (highly priority) or `figi`.
3547
3548        :param portfolio: dict with user's portfolio data. If `None`, then requests portfolio from `Overview()` method.
3549        :return: dict with instrument if portfolio contains open position with this instrument, `None` otherwise.
3550        """
3551        result = None
3552        msg = "Instrument not defined!"
3553
3554        if portfolio is None or not portfolio:
3555            portfolio = self.Overview(show=False)
3556
3557        if self.ticker:
3558            uLogger.debug("Searching instrument with ticker [{}] throwout opened positions...".format(self.ticker))
3559            msg = "Instrument with ticker [{}] is not present in open positions".format(self.ticker)
3560
3561            for iType in TKS_INSTRUMENTS:
3562                for instrument in portfolio["stat"][iType]:
3563                    if instrument["ticker"] == self.ticker:
3564                        result = instrument
3565                        msg = "Instrument with ticker [{}] and FIGI [{}] is present in open positions".format(self.ticker, instrument["figi"])
3566                        break
3567
3568        elif self.figi:
3569            uLogger.debug("Searching instrument with FIGI [{}] throwout opened positions...".format(self.figi))
3570            msg = "Instrument with FIGI [{}] is not present in open positions".format(self.figi)
3571
3572            for iType in TKS_INSTRUMENTS:
3573                for instrument in portfolio["stat"][iType]:
3574                    if instrument["figi"] == self.figi:
3575                        result = instrument
3576                        msg = "Instrument with ticker [{}] and FIGI [{}] is present in open positions".format(instrument["ticker"], self.figi)
3577                        break
3578
3579        else:
3580            uLogger.warning("Instrument must be defined by `ticker` (highly priority) or `figi`!")
3581
3582        uLogger.debug(msg)
3583
3584        return result
3585
3586    def RequestLimits(self) -> dict:
3587        """
3588        Method for obtaining the available funds for withdrawal for current `accountId`.
3589
3590        See also:
3591        - REST API for limits: https://tinkoff.github.io/investAPI/swagger-ui/#/OperationsService/OperationsService_GetWithdrawLimits
3592        - `OverviewLimits()` method
3593
3594        :return: dict with raw data from server that contains free funds for withdrawal. Example of dict:
3595                 `{"money": [{"currency": "rub", "units": "100", "nano": 290000000}, {...}], "blocked": [...], "blockedGuarantee": [...]}`.
3596                 Here `money` is an array of portfolio currency positions, `blocked` is an array of blocked currency
3597                 positions of the portfolio and `blockedGuarantee` is locked money under collateral for futures.
3598        """
3599        if self.accountId is None or not self.accountId:
3600            uLogger.error("Variable `accountId` must be defined for using this method!")
3601            raise Exception("Account ID required")
3602
3603        uLogger.debug("Requesting current available funds for withdrawal. Wait, please...")
3604
3605        self.body = str({"accountId": self.accountId})
3606        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.OperationsService/GetWithdrawLimits"
3607        rawLimits = self.SendAPIRequest(portfolioURL, reqType="POST")
3608
3609        if self.moreDebug:
3610            uLogger.debug("Records about available funds for withdrawal successfully received")
3611
3612        return rawLimits
3613
3614    def OverviewLimits(self, show: bool = False) -> dict:
3615        """
3616        Method for parsing and show table with available funds for withdrawal for current `accountId`.
3617
3618        See also: `RequestLimits()`.
3619
3620        :param show: if `False` then only dictionary returns, if `True` then also print withdrawal limits to log.
3621        :return: dict with raw parsed data from server and some calculated statistics about it.
3622        """
3623        if self.accountId is None or not self.accountId:
3624            uLogger.error("Variable `accountId` must be defined for using this method!")
3625            raise Exception("Account ID required")
3626
3627        rawLimits = self.RequestLimits()  # raw response with current available funds for withdrawal
3628
3629        view = {
3630            "rawLimits": rawLimits,
3631            "limits": {  # parsed data for every currency:
3632                "money": {  # this is an array of portfolio currency positions
3633                    item["currency"]: NanoToFloat(item["units"], item["nano"]) for item in rawLimits["money"]
3634                },
3635                "blocked": {  # this is an array of blocked currency
3636                    item["currency"]: NanoToFloat(item["units"], item["nano"]) for item in rawLimits["blocked"]
3637                },
3638                "blockedGuarantee": {  # this is locked money under collateral for futures
3639                    item["currency"]: NanoToFloat(item["units"], item["nano"]) for item in rawLimits["blockedGuarantee"]
3640                },
3641            },
3642        }
3643
3644        # --- Prepare text table with limits in human-readable format:
3645        if show:
3646            info = [
3647                "# Withdrawal limits\n\n",
3648                "* **Actual date:** [{} UTC]\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
3649                "* **Account ID:** [{}]\n".format(self.accountId),
3650            ]
3651
3652            if view["limits"]["money"]:
3653                info.extend([
3654                    "\n| Currencies | Total         | Available for withdrawal | Blocked for trade | Futures guarantee |\n",
3655                    "|------------|---------------|--------------------------|-------------------|-------------------|\n",
3656                ])
3657
3658            else:
3659                info.append("\nNo withdrawal limits\n")
3660
3661            for curr in view["limits"]["money"].keys():
3662                blocked = view["limits"]["blocked"][curr] if curr in view["limits"]["blocked"].keys() else 0
3663                blockedGuarantee = view["limits"]["blockedGuarantee"][curr] if curr in view["limits"]["blockedGuarantee"].keys() else 0
3664                availableMoney = view["limits"]["money"][curr] - (blocked + blockedGuarantee)
3665
3666                infoStr = "| {:<10} | {:<13} | {:<24} | {:<17} | {:<17} |\n".format(
3667                    "[{}]".format(curr),
3668                    "{:.2f}".format(view["limits"]["money"][curr]),
3669                    "{:.2f}".format(availableMoney),
3670                    "{:.2f}".format(view["limits"]["blocked"][curr]) if curr in view["limits"]["blocked"].keys() else "—",
3671                    "{:.2f}".format(view["limits"]["blockedGuarantee"][curr]) if curr in view["limits"]["blockedGuarantee"].keys() else "—",
3672                )
3673
3674                if curr == "rub":
3675                    info.insert(5, infoStr)  # hack: insert "rub" at the first position in table and after headers
3676
3677                else:
3678                    info.append(infoStr)
3679
3680            infoText = "".join(info)
3681
3682            uLogger.info(infoText)
3683
3684            if self.withdrawalLimitsFile:
3685                with open(self.withdrawalLimitsFile, "w", encoding="UTF-8") as fH:
3686                    fH.write(infoText)
3687
3688                uLogger.info("Client's withdrawal limits was saved to file: [{}]".format(os.path.abspath(self.withdrawalLimitsFile)))
3689
3690        return view
3691
3692    def RequestAccounts(self) -> dict:
3693        """
3694        Method for requesting all brokerage accounts (`accountId`s) of current user detected by `token`.
3695
3696        See also:
3697        - REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/UsersService/UsersService_GetAccounts
3698        - What does account fields mean: https://tinkoff.github.io/investAPI/users/#account
3699        - `OverviewUserInfo()` method
3700
3701        :return: dict with raw data from server that contains accounts info. Example of dict:
3702                 `{"accounts": [{"id": "20000xxxxx", "type": "ACCOUNT_TYPE_TINKOFF", "name": "TKSBrokerAPI account",
3703                   "status": "ACCOUNT_STATUS_OPEN", "openedDate": "2018-05-23T00:00:00Z",
3704                   "closedDate": "1970-01-01T00:00:00Z", "accessLevel": "ACCOUNT_ACCESS_LEVEL_FULL_ACCESS"}, ...]}`.
3705                 If `closedDate="1970-01-01T00:00:00Z"` it means that account is active now.
3706        """
3707        uLogger.debug("Requesting all brokerage accounts of current user detected by its token. Wait, please...")
3708
3709        self.body = str({})
3710        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.UsersService/GetAccounts"
3711        rawAccounts = self.SendAPIRequest(portfolioURL, reqType="POST")
3712
3713        if self.moreDebug:
3714            uLogger.debug("Records about available accounts successfully received")
3715
3716        return rawAccounts
3717
3718    def RequestUserInfo(self) -> dict:
3719        """
3720        Method for requesting common user's information.
3721
3722        See also:
3723        - REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/UsersService/UsersService_GetInfo
3724        - What does user info fields mean: https://tinkoff.github.io/investAPI/users/#getinforequest
3725        - What does `qualified_for_work_with` field mean: https://tinkoff.github.io/investAPI/faq_users/#qualified_for_work_with
3726        - `OverviewUserInfo()` method
3727
3728        :return: dict with raw data from server that contains user's information. Example of dict:
3729                 `{"premStatus": true, "qualStatus": false, "qualifiedForWorkWith": ["bond", "foreign_shares", "leverage",
3730                   "russian_shares", "structured_income_bonds"], "tariff": "premium"}`.
3731        """
3732        uLogger.debug("Requesting common user's information. Wait, please...")
3733
3734        self.body = str({})
3735        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.UsersService/GetInfo"
3736        rawUserInfo = self.SendAPIRequest(portfolioURL, reqType="POST")
3737
3738        if self.moreDebug:
3739            uLogger.debug("Records about current user successfully received")
3740
3741        return rawUserInfo
3742
3743    def RequestMarginStatus(self, accountId: str = None) -> dict:
3744        """
3745        Method for requesting margin calculation for defined account ID.
3746
3747        See also:
3748        - REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/UsersService/UsersService_GetMarginAttributes
3749        - What does margin fields mean: https://tinkoff.github.io/investAPI/users/#getmarginattributesresponse
3750        - `OverviewUserInfo()` method
3751
3752        :param accountId: string with numeric account ID. If `None`, then used class field `accountId`.
3753        :return: dict with raw data from server that contains margin calculation. If margin is disabled then returns empty dict.
3754                 Example of responses:
3755                 status code 400: `{"code": 3, "message": "account margin status is disabled", "description": "30051" }`, returns: `{}`.
3756                 status code 200: `{"liquidPortfolio": {"currency": "rub", "units": "7175", "nano": 560000000},
3757                                    "startingMargin": {"currency": "rub", "units": "6311", "nano": 840000000},
3758                                    "minimalMargin": {"currency": "rub", "units": "3155", "nano": 920000000},
3759                                    "fundsSufficiencyLevel": {"units": "1", "nano": 280000000},
3760                                    "amountOfMissingFunds": {"currency": "rub", "units": "-863", "nano": -720000000}}`.
3761        """
3762        if accountId is None or not accountId:
3763            if self.accountId is None or not self.accountId:
3764                uLogger.error("Variable `accountId` must be defined for using this method!")
3765                raise Exception("Account ID required")
3766
3767            else:
3768                accountId = self.accountId  # use `self.accountId` (main ID) by default
3769
3770        uLogger.debug("Requesting margin calculation for accountId [{}]. Wait, please...".format(accountId))
3771
3772        self.body = str({"accountId": accountId})
3773        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.UsersService/GetMarginAttributes"
3774        rawMargin = self.SendAPIRequest(portfolioURL, reqType="POST")
3775
3776        if rawMargin == {"code": 3, "message": "account margin status is disabled", "description": "30051"}:
3777            uLogger.debug("Server response: margin status is disabled for current accountId [{}]".format(accountId))
3778            rawMargin = {}
3779
3780        else:
3781            if self.moreDebug:
3782                uLogger.debug("Records with margin calculation for accountId [{}] successfully received".format(accountId))
3783
3784        return rawMargin
3785
3786    def RequestTariffLimits(self) -> dict:
3787        """
3788        Method for requesting limits of current tariff (connections, API methods etc.) of current user detected by `token`.
3789
3790        See also:
3791        - REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/UsersService/UsersService_GetUserTariff
3792        - What does fields in tariff mean: https://tinkoff.github.io/investAPI/users/#getusertariffrequest
3793        - Unary limit: https://tinkoff.github.io/investAPI/users/#unarylimit
3794        - Stream limit: https://tinkoff.github.io/investAPI/users/#streamlimit
3795        - `OverviewUserInfo()` method
3796
3797        :return: dict with raw data from server that contains limits of current tariff. Example of dict:
3798                 `{"unaryLimits": [{"limitPerMinute": 0, "methods": ["methods", "methods"]}, ...],
3799                   "streamLimits": [{"streams": ["streams", "streams"], "limit": 6}, ...]}`.
3800        """
3801        uLogger.debug("Requesting limits of current tariff. Wait, please...")
3802
3803        self.body = str({})
3804        portfolioURL = self.server + r"/tinkoff.public.invest.api.contract.v1.UsersService/GetUserTariff"
3805        rawTariffLimits = self.SendAPIRequest(portfolioURL, reqType="POST")
3806
3807        if self.moreDebug:
3808            uLogger.debug("Records with limits of current tariff successfully received")
3809
3810        return rawTariffLimits
3811
3812    def RequestBondCoupons(self, iJSON: dict) -> dict:
3813        """
3814        Requesting bond payment calendar from official placement date to maturity date. If these dates are unknown
3815        then requesting dates `"from": "1970-01-01T00:00:00.000Z"` and `"to": "2099-12-31T23:59:59.000Z"`.
3816        All dates are in UTC timezone.
3817
3818        REST API: https://tinkoff.github.io/investAPI/swagger-ui/#/InstrumentsService/InstrumentsService_GetBondCoupons
3819        Documentation:
3820        - request: https://tinkoff.github.io/investAPI/instruments/#getbondcouponsrequest
3821        - response: https://tinkoff.github.io/investAPI/instruments/#coupon
3822
3823        See also: `ExtendBondsData()`.
3824
3825        :param iJSON: raw json data of a bond from broker server, example `iJSON = self.iList["Bonds"][self.ticker]`
3826                      If raw iJSON is not data of bond then server returns an error [400] with message:
3827                      `{"code": 3, "message": "instrument type is not bond", "description": "30048"}`.
3828        :return: dictionary with bond payment calendar. Response example
3829                 `{"events": [{"figi": "TCS00A101YV8", "couponDate": "2023-07-26T00:00:00Z", "couponNumber": "12",
3830                   "fixDate": "2023-07-25T00:00:00Z", "payOneBond": {"currency": "rub", "units": "7", "nano": 170000000},
3831                   "couponType": "COUPON_TYPE_CONSTANT", "couponStartDate": "2023-04-26T00:00:00Z",
3832                   "couponEndDate": "2023-07-26T00:00:00Z", "couponPeriod": 91}, {...}, ...]}`
3833        """
3834        if iJSON["figi"] is None or not iJSON["figi"]:
3835            uLogger.error("FIGI must be defined for using this method!")
3836            raise Exception("FIGI required")
3837
3838        startDate = iJSON["placementDate"] if "placementDate" in iJSON.keys() else "1970-01-01T00:00:00.000Z"
3839        endDate = iJSON["maturityDate"] if "maturityDate" in iJSON.keys() else "2099-12-31T23:59:59.000Z"
3840
3841        uLogger.debug("Requesting bond payment calendar, {}FIGI: [{}], from: [{}], to: [{}]. Wait, please...".format(
3842            "ticker: [{}], ".format(iJSON["ticker"]) if "ticker" in iJSON.keys() else "",
3843            self.figi,
3844            startDate,
3845            endDate,
3846        ))
3847
3848        self.body = str({"figi": iJSON["figi"], "from": startDate, "to": endDate})
3849        calendarURL = self.server + r"/tinkoff.public.invest.api.contract.v1.InstrumentsService/GetBondCoupons"
3850        calendar = self.SendAPIRequest(calendarURL, reqType="POST")
3851
3852        if calendar == {"code": 3, "message": "instrument type is not bond", "description": "30048"}:
3853            uLogger.warning("Instrument type is not bond!")
3854
3855        else:
3856            if self.moreDebug:
3857                uLogger.debug("Records about bond payment calendar successfully received")
3858
3859        return calendar
3860
3861    def ExtendBondsData(self, instruments: list[str], xlsx: bool = False) -> pd.DataFrame:
3862        """
3863        Requests jsons with raw bonds data for every ticker or FIGI in instruments list and transform it to the wider
3864        Pandas DataFrame with more information about bonds: main info, current prices, bond payment calendar,
3865        coupon yields, current yields and some statistics etc.
3866
3867        WARNING! This is too long operation if a lot of bonds requested from broker server.
3868
3869        See also: `ShowInstrumentInfo()`, `CreateBondsCalendar()`, `ShowBondsCalendar()`, `RequestBondCoupons()`.
3870
3871        :param instruments: list of strings with tickers or FIGIs.
3872        :param xlsx: if True then also exports Pandas DataFrame to xlsx-file `bondsXLSXFile`, default `ext-bonds.xlsx`,
3873                     for further used by data scientists or stock analytics.
3874        :return: wider Pandas DataFrame with more full and calculated data about bonds, than raw response from broker.
3875                 In XLSX-file and Pandas DataFrame fields mean:
3876                 - main info about bond: https://tinkoff.github.io/investAPI/instruments/#bond
3877                 - info about coupon: https://tinkoff.github.io/investAPI/instruments/#coupon
3878        """
3879        if instruments is None or not instruments:
3880            uLogger.error("List of tickers or FIGIs must be defined for using this method!")
3881            raise Exception("Ticker or FIGI required")
3882
3883        if isinstance(instruments, str):
3884            instruments = [instruments]
3885
3886        uniqueInstruments = self.GetUniqueFIGIs(instruments)
3887
3888        uLogger.debug("Requesting raw bonds calendar from server, transforming and extending it. Wait, please...")
3889
3890        iCount = len(uniqueInstruments)
3891        tooLong = iCount >= 20
3892        if tooLong:
3893            uLogger.warning("You requested a lot of bonds! Operation will takes more time. Wait, please...")
3894
3895        bonds = None
3896        for i, self.figi in enumerate(uniqueInstruments):
3897            instrument = self.SearchByFIGI(requestPrice=False)  # raw data about instrument from server
3898
3899            if "type" in instrument.keys() and instrument["type"] == "Bonds":
3900                # raw bond data from server where fields mean: https://tinkoff.github.io/investAPI/instruments/#bond
3901                rawBond = self.SearchByFIGI(requestPrice=True)
3902
3903                # Widen raw data with UTC current time (iData["actualDateTime"]):
3904                actualDate = datetime.now(tzutc())
3905                iData = {"actualDateTime": actualDate.strftime(TKS_DATE_TIME_FORMAT)} | rawBond
3906
3907                # Widen raw data with bond payment calendar (iData["rawCalendar"]):
3908                iData = iData | {"rawCalendar": self.RequestBondCoupons(iJSON=iData)}
3909
3910                # Replace some values with human-readable:
3911                iData["nominalCurrency"] = iData["nominal"]["currency"]
3912                iData["nominal"] = NanoToFloat(iData["nominal"]["units"], iData["nominal"]["nano"])
3913                iData["placementPrice"] = NanoToFloat(iData["placementPrice"]["units"], iData["placementPrice"]["nano"])
3914                iData["aciCurrency"] = iData["aciValue"]["currency"]
3915                iData["aciValue"] = NanoToFloat(iData["aciValue"]["units"], iData["aciValue"]["nano"])
3916                iData["issueSize"] = int(iData["issueSize"])
3917                iData["issueSizePlan"] = int(iData["issueSizePlan"])
3918                iData["tradingStatus"] = TKS_TRADING_STATUSES[iData["tradingStatus"]]
3919                iData["step"] = iData["step"] if "step" in iData.keys() else 0
3920                iData["realExchange"] = TKS_REAL_EXCHANGES[iData["realExchange"]]
3921                iData["klong"] = NanoToFloat(iData["klong"]["units"], iData["klong"]["nano"]) if "klong" in iData.keys() else 0
3922                iData["kshort"] = NanoToFloat(iData["kshort"]["units"], iData["kshort"]["nano"]) if "kshort" in iData.keys() else 0
3923                iData["dlong"] = NanoToFloat(iData["dlong"]["units"], iData["dlong"]["nano"]) if "dlong" in iData.keys() else 0
3924                iData["dshort"] = NanoToFloat(iData["dshort"]["units"], iData["dshort"]["nano"]) if "dshort" in iData.keys() else 0
3925                iData["dlongMin"] = NanoToFloat(iData["dlongMin"]["units"], iData["dlongMin"]["nano"]) if "dlongMin" in iData.keys() else 0
3926                iData["dshortMin"] = NanoToFloat(iData["dshortMin"]["units"], iData["dshortMin"]["nano"]) if "dshortMin" in iData.keys() else 0
3927
3928                # Widen raw data with price fields from `currentPrice` values (all prices are actual at `actualDateTime` date):
3929                iData["limitUpPercent"] = iData["currentPrice"]["limitUp"]  # max price on current day in percents of nominal
3930                iData["limitDownPercent"] = iData["currentPrice"]["limitDown"]  # min price on current day in percents of nominal
3931                iData["lastPricePercent"] = iData["currentPrice"]["lastPrice"]  # last price on market in percents of nominal
3932                iData["closePricePercent"] = iData["currentPrice"]["closePrice"]  # previous day close in percents of nominal
3933                iData["changes"] = iData["currentPrice"]["changes"]  # this is percent of changes between `currentPrice` and `lastPrice`
3934                iData["limitUp"] = iData["limitUpPercent"] * iData["nominal"] / 100  # max price on current day is `limitUpPercent` * `nominal`
3935                iData["limitDown"] = iData["limitDownPercent"] * iData["nominal"] / 100  # min price on current day is `limitDownPercent` * `nominal`
3936                iData["lastPrice"] = iData["lastPricePercent"] * iData["nominal"] / 100  # last price on market is `lastPricePercent` * `nominal`
3937                iData["closePrice"] = iData["closePricePercent"] * iData["nominal"] / 100  # previous day close is `closePricePercent` * `nominal`
3938                iData["changesDelta"] = iData["lastPrice"] - iData["closePrice"]  # this is delta between last deal price and last close
3939
3940                # Widen raw data with calendar data from `rawCalendar` values:
3941                calendarData = []
3942                if "events" in iData["rawCalendar"].keys():
3943                    for item in iData["rawCalendar"]["events"]:
3944                        calendarData.append({
3945                            "couponDate": item["couponDate"],
3946                            "couponNumber": int(item["couponNumber"]),
3947                            "fixDate": item["fixDate"] if "fixDate" in item.keys() else "",
3948                            "payCurrency": item["payOneBond"]["currency"],
3949                            "payOneBond": NanoToFloat(item["payOneBond"]["units"], item["payOneBond"]["nano"]),
3950                            "couponType": TKS_COUPON_TYPES[item["couponType"]],
3951                            "couponStartDate": item["couponStartDate"],
3952                            "couponEndDate": item["couponEndDate"],
3953                            "couponPeriod": item["couponPeriod"],
3954                        })
3955
3956                    # if maturity date is unknown then uses the latest date in bond payment calendar for it:
3957                    if "maturityDate" not in iData.keys():
3958                        iData["maturityDate"] = datetime.strptime(calendarData[0]["couponDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()).strftime(TKS_DATE_TIME_FORMAT) if calendarData else ""
3959
3960                # Widen raw data with Coupon Rate.
3961                # This is sum of all coupon payments divided on nominal price and expire days sum and then multiple on 365 days and 100%:
3962                iData["sumCoupons"] = sum([coupon["payOneBond"] for coupon in calendarData])
3963                iData["periodDays"] = sum([coupon["couponPeriod"] for coupon in calendarData])
3964                iData["couponsYield"] = 100 * 365 * (iData["sumCoupons"] / iData["nominal"]) / iData["periodDays"] if iData["nominal"] != 0 and iData["periodDays"] != 0 else 0.
3965
3966                # Widen raw data with Yield to Maturity (YTM) on current date.
3967                # This is sum of all stayed coupons to maturity minus ACI and divided on current bond price and then multiple on stayed days and 100%:
3968                maturityDate = datetime.strptime(iData["maturityDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()) if iData["maturityDate"] else None
3969                iData["daysToMaturity"] = (maturityDate - actualDate).days if iData["maturityDate"] else None
3970                iData["sumLastCoupons"] = sum([coupon["payOneBond"] for coupon in calendarData if datetime.strptime(coupon["couponDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()) > actualDate])
3971                iData["lastPayments"] = iData["sumLastCoupons"] - iData["aciValue"]  # sum of all last coupons minus current ACI value
3972                iData["currentYield"] = 100 * 365 * (iData["lastPayments"] / iData["lastPrice"]) / iData["daysToMaturity"] if iData["lastPrice"] != 0 and iData["daysToMaturity"] != 0 else 0.
3973
3974                iData["calendar"] = calendarData  # adds calendar at the end
3975
3976                # Remove not used data:
3977                iData.pop("uid")
3978                iData.pop("positionUid")
3979                iData.pop("currentPrice")
3980                iData.pop("rawCalendar")
3981
3982                colNames = list(iData.keys())
3983                if bonds is None:
3984                    bonds = pd.DataFrame(data=pd.DataFrame.from_records(data=[iData], columns=colNames))
3985
3986                else:
3987                    bonds = pd.concat([bonds, pd.DataFrame.from_records(data=[iData], columns=colNames)], axis=0, ignore_index=True)
3988
3989            else:
3990                uLogger.warning("Instrument is not a bond!")
3991
3992            processed = round(100 * (i + 1) / iCount, 1)
3993            if tooLong and processed % 5 == 0:
3994                uLogger.info("{}% processed [{} / {}]...".format(round(processed), i + 1, iCount))
3995
3996            else:
3997                uLogger.debug("{}% bonds processed [{} / {}]...".format(processed, i + 1, iCount))
3998
3999        bonds.index = bonds["ticker"].tolist()  # replace indexes with ticker names
4000
4001        # Saving bonds from Pandas DataFrame to XLSX sheet:
4002        if xlsx and self.bondsXLSXFile:
4003            with pd.ExcelWriter(
4004                    path=self.bondsXLSXFile,
4005                    date_format=TKS_DATE_FORMAT,
4006                    datetime_format=TKS_DATE_TIME_FORMAT,
4007                    mode="w",
4008            ) as writer:
4009                bonds.to_excel(
4010                    writer,
4011                    sheet_name="Extended bonds data",
4012                    index=True,
4013                    encoding="UTF-8",
4014                    freeze_panes=(1, 1),
4015                )  # saving as XLSX-file with freeze first row and column as headers
4016
4017            uLogger.info("XLSX-file with extended bonds data for further used by data scientists or stock analytics: [{}]".format(os.path.abspath(self.bondsXLSXFile)))
4018
4019        return bonds
4020
4021    def CreateBondsCalendar(self, extBonds: pd.DataFrame, xlsx: bool = False) -> pd.DataFrame:
4022        """
4023        Creates bond payments calendar as Pandas DataFrame, and also save it to the XLSX-file, `calendar.xlsx` by default.
4024
4025        WARNING! This is too long operation if a lot of bonds requested from broker server.
4026
4027        See also: `ShowBondsCalendar()`, `ExtendBondsData()`.
4028
4029        :param extBonds: Pandas DataFrame object returns by `ExtendBondsData()` method and contains
4030                        extended information about bonds: main info, current prices, bond payment calendar,
4031                        coupon yields, current yields and some statistics etc.
4032                        If this parameter is `None` then used `figi` or `ticker` as bond name and then calculate `ExtendBondsData()`.
4033        :param xlsx: if True then also exports Pandas DataFrame to file `calendarFile` + `".xlsx"`, `calendar.xlsx` by default,
4034                     for further used by data scientists or stock analytics.
4035        :return: Pandas DataFrame with only bond payments calendar data. Fields mean: https://tinkoff.github.io/investAPI/instruments/#coupon
4036        """
4037        if extBonds is None or not isinstance(extBonds, pd.DataFrame) or extBonds.empty:
4038            extBonds = self.ExtendBondsData(instruments=[self.figi, self.ticker], xlsx=False)
4039
4040        uLogger.debug("Generating bond payments calendar data. Wait, please...")
4041
4042        colNames = ["Paid", "Payment date", "FIGI", "Ticker", "Name", "No.", "Value", "Currency", "Coupon type", "Period", "End registry date", "Coupon start date", "Coupon end date"]
4043        colID = ["paid", "couponDate", "figi", "ticker", "name", "couponNumber", "payOneBond", "payCurrency", "couponType", "couponPeriod", "fixDate", "couponStartDate", "couponEndDate"]
4044        calendar = None
4045        for bond in extBonds.iterrows():
4046            for item in bond[1]["calendar"]:
4047                cData = {
4048                    "paid": datetime.now(tzutc()) > datetime.strptime(item["couponDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()),
4049                    "couponDate": item["couponDate"],
4050                    "figi": bond[1]["figi"],
4051                    "ticker": bond[1]["ticker"],
4052                    "name": bond[1]["name"],
4053                    "couponNumber": item["couponNumber"],
4054                    "payOneBond": item["payOneBond"],
4055                    "payCurrency": item["payCurrency"],
4056                    "couponType": item["couponType"],
4057                    "couponPeriod": item["couponPeriod"],
4058                    "fixDate": item["fixDate"],
4059                    "couponStartDate": item["couponStartDate"],
4060                    "couponEndDate": item["couponEndDate"],
4061                }
4062
4063                if calendar is None:
4064                    calendar = pd.DataFrame(data=pd.DataFrame.from_records(data=[cData], columns=colID))
4065
4066                else:
4067                    calendar = pd.concat([calendar, pd.DataFrame.from_records(data=[cData], columns=colID)], axis=0, ignore_index=True)
4068
4069        if calendar is not None:
4070            calendar = calendar.sort_values(by=["couponDate"], axis=0, ascending=True)  # sort all payments for all bonds by payment date
4071
4072            # Saving calendar from Pandas DataFrame to XLSX sheet:
4073            if xlsx:
4074                xlsxCalendarFile = self.calendarFile.replace(".md", ".xlsx") if self.calendarFile.endswith(".md") else self.calendarFile + ".xlsx"
4075
4076                with pd.ExcelWriter(
4077                        path=xlsxCalendarFile,
4078                        date_format=TKS_DATE_FORMAT,
4079                        datetime_format=TKS_DATE_TIME_FORMAT,
4080                        mode="w",
4081                ) as writer:
4082                    humanReadable = calendar.copy(deep=True)
4083                    humanReadable["couponDate"] = humanReadable["couponDate"].apply(lambda x: x.split("T")[0])
4084                    humanReadable["fixDate"] = humanReadable["fixDate"].apply(lambda x: x.split("T")[0])
4085                    humanReadable["couponStartDate"] = humanReadable["couponStartDate"].apply(lambda x: x.split("T")[0])
4086                    humanReadable["couponEndDate"] = humanReadable["couponEndDate"].apply(lambda x: x.split("T")[0])
4087                    humanReadable.columns = colNames  # human-readable column names
4088
4089                    humanReadable.to_excel(
4090                        writer,
4091                        sheet_name="Bond payments calendar",
4092                        index=False,
4093                        encoding="UTF-8",
4094                        freeze_panes=(1, 2),
4095                    )  # saving as XLSX-file with freeze first row and column as headers
4096
4097                    del humanReadable  # release df in memory
4098
4099                uLogger.info("XLSX-file with bond payments calendar for further used by data scientists or stock analytics: [{}]".format(os.path.abspath(xlsxCalendarFile)))
4100
4101        return calendar
4102
4103    def ShowBondsCalendar(self, extBonds: pd.DataFrame, show: bool = True) -> str:
4104        """
4105        Show bond payments calendar as a table. One row in input `bonds` dataframe contains one bond.
4106        Also, creates Markdown file with calendar data, `calendar.md` by default.
4107
4108        See also: `ShowInstrumentInfo()`, `RequestBondCoupons()`, `CreateBondsCalendar()` and `ExtendBondsData()`.
4109
4110        :param extBonds: Pandas DataFrame object returns by `ExtendBondsData()` method and contains
4111                        extended information about bonds: main info, current prices, bond payment calendar,
4112                        coupon yields, current yields and some statistics etc.
4113                        If this parameter is `None` then used `figi` or `ticker` as bond name and then calculate `ExtendBondsData()`.
4114        :param show: if `True` then also printing bonds payment calendar to the console,
4115                     otherwise save to file `calendarFile` only. `False` by default.
4116        :return: multilines text in Markdown format with bonds payment calendar as a table.
4117        """
4118        if extBonds is None or not isinstance(extBonds, pd.DataFrame) or extBonds.empty:
4119            extBonds = self.ExtendBondsData(instruments=[self.figi, self.ticker], xlsx=False)
4120
4121        infoText = "# Bond payments calendar\n\n"
4122
4123        calendar = self.CreateBondsCalendar(extBonds, xlsx=True)  # generate Pandas DataFrame with full calendar data
4124
4125        if not (calendar is None or calendar.empty):
4126            splitLine = "|       |                 |              |              |     |               |           |        |                   |\n"
4127
4128            info = [
4129                "| Paid  | Payment date    | FIGI         | Ticker       | No. | Value         | Type      | Period | End registry date |\n",
4130                "|-------|-----------------|--------------|--------------|-----|---------------|-----------|--------|-------------------|\n",
4131            ]
4132
4133            newMonth = False
4134            notOneBond = calendar["figi"].nunique() > 1
4135            for i, bond in enumerate(calendar.iterrows()):
4136                if newMonth and notOneBond:
4137                    info.append(splitLine)
4138
4139                info.append(
4140                    "| {:<5} | {:<15} | {:<12} | {:<12} | {:<3} | {:<13} | {:<9} | {:<6} | {:<17} |\n".format(
4141                        "  √" if bond[1]["paid"] else "  —",
4142                        bond[1]["couponDate"].split("T")[0],
4143                        bond[1]["figi"],
4144                        bond[1]["ticker"],
4145                        bond[1]["couponNumber"],
4146                        "{} {}".format(
4147                            "{}".format(round(bond[1]["payOneBond"], 6)).rstrip("0").rstrip("."),
4148                            bond[1]["payCurrency"],
4149                        ),
4150                        bond[1]["couponType"],
4151                        bond[1]["couponPeriod"],
4152                        bond[1]["fixDate"].split("T")[0],
4153                    )
4154                )
4155
4156                if i < len(calendar.values) - 1:
4157                    curDate = datetime.strptime(bond[1]["couponDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc())
4158                    nextDate = datetime.strptime(calendar["couponDate"].values[i + 1], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc())
4159                    newMonth = False if curDate.month == nextDate.month else True
4160
4161                else:
4162                    newMonth = False
4163
4164            infoText += "".join(info)
4165
4166            if show:
4167                uLogger.info("{}".format(infoText))
4168
4169            if self.calendarFile is not None:
4170                with open(self.calendarFile, "w", encoding="UTF-8") as fH:
4171                    fH.write(infoText)
4172
4173                uLogger.info("Bond payment calendar was saved to file: [{}]".format(os.path.abspath(self.calendarFile)))
4174
4175        else:
4176            infoText += "No data\n"
4177
4178        return infoText
4179
4180    def OverviewAccounts(self, show: bool = False) -> dict:
4181        """
4182        Method for parsing and show simple table with all available user accounts.
4183
4184        See also: `RequestAccounts()` and `OverviewUserInfo()` methods.
4185
4186        :param show: if `False` then only dictionary with accounts data returns, if `True` then also print it to log.
4187        :return: dict with parsed accounts data received from `RequestAccounts()` method. Example of dict:
4188                 `view = {"rawAccounts": {rawAccounts from RequestAccounts() method...},
4189                          "stat": {"accountId string": {"type": "Tinkoff brokerage account", "name": "Test - 1",
4190                                                        "status": "Opened and active account", "opened": "2018-05-23 00:00:00",
4191                                                        "closed": "—", "access": "Full access" }, ...}}`
4192        """
4193        rawAccounts = self.RequestAccounts()  # Raw responses with accounts
4194
4195        # This is an array of dict with user accounts, its `accountId`s and some parsed data:
4196        accounts = {
4197            item["id"]: {
4198                "type": TKS_ACCOUNT_TYPES[item["type"]],
4199                "name": item["name"],
4200                "status": TKS_ACCOUNT_STATUSES[item["status"]],
4201                "opened": datetime.strptime(item["openedDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT),
4202                "closed": datetime.strptime(item["closedDate"], TKS_DATE_TIME_FORMAT).replace(tzinfo=tzutc()).astimezone(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT) if item["closedDate"] != "1970-01-01T00:00:00Z" else "—",
4203                "access": TKS_ACCESS_LEVELS[item["accessLevel"]],
4204            } for item in rawAccounts["accounts"]
4205        }
4206
4207        # Raw and parsed data with some fields replaced in "stat" section:
4208        view = {
4209            "rawAccounts": rawAccounts,
4210            "stat": accounts,
4211        }
4212
4213        # --- Prepare simple text table with only accounts data in human-readable format:
4214        if show:
4215            info = [
4216                "# User accounts\n\n",
4217                "* **Actual date:** [{} UTC]\n\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
4218                "| Account ID   | Type                      | Status                    | Name                           |\n",
4219                "|--------------|---------------------------|---------------------------|--------------------------------|\n",
4220            ]
4221
4222            for account in view["stat"].keys():
4223                info.extend([
4224                    "| {:<12} | {:<25} | {:<25} | {:<30} |\n".format(
4225                        account,
4226                        view["stat"][account]["type"],
4227                        view["stat"][account]["status"],
4228                        view["stat"][account]["name"],
4229                    )
4230                ])
4231
4232            infoText = "".join(info)
4233
4234            uLogger.info(infoText)
4235
4236            if self.userAccountsFile:
4237                with open(self.userAccountsFile, "w", encoding="UTF-8") as fH:
4238                    fH.write(infoText)
4239
4240                uLogger.info("User accounts were saved to file: [{}]".format(os.path.abspath(self.userAccountsFile)))
4241
4242        return view
4243
4244    def OverviewUserInfo(self, show: bool = False) -> dict:
4245        """
4246        Method for parsing and show all available user's data (`accountId`s, common user information, margin status and tariff connections limit).
4247
4248        See also: `OverviewAccounts()`, `RequestAccounts()`, `RequestUserInfo()`, `RequestMarginStatus()` and `RequestTariffLimits()` methods.
4249
4250        :param show: if `False` then only dictionary returns, if `True` then also print user's data to log.
4251        :return: dict with raw parsed data from server and some calculated statistics about it.
4252        """
4253        rawUserInfo = self.RequestUserInfo()  # Raw response with common user info
4254        overviewAccount = self.OverviewAccounts(show=False)  # Raw and parsed accounts data
4255        rawAccounts = overviewAccount["rawAccounts"]  # Raw response with user accounts data
4256        accounts = overviewAccount["stat"]  # Dict with only statistics about user accounts
4257        rawMargins = {account: self.RequestMarginStatus(accountId=account) for account in accounts.keys()}  # Raw response with margin calculation for every account ID
4258        rawTariffLimits = self.RequestTariffLimits()  # Raw response with limits of current tariff
4259
4260        # This is dict with parsed common user data:
4261        userInfo = {
4262            "premium": "Yes" if rawUserInfo["premStatus"] else "No",
4263            "qualified": "Yes" if rawUserInfo["qualStatus"] else "No",
4264            "allowed": [TKS_QUALIFIED_TYPES[item] for item in rawUserInfo["qualifiedForWorkWith"]],
4265            "tariff": rawUserInfo["tariff"],
4266        }
4267
4268        # This is an array of dict with parsed margin statuses for every account IDs:
4269        margins = {}
4270        for accountId in accounts.keys():
4271            if rawMargins[accountId]:
4272                margins[accountId] = {
4273                    "currency": rawMargins[accountId]["liquidPortfolio"]["currency"],
4274                    "liquid": NanoToFloat(rawMargins[accountId]["liquidPortfolio"]["units"], rawMargins[accountId]["liquidPortfolio"]["nano"]),
4275                    "start": NanoToFloat(rawMargins[accountId]["startingMargin"]["units"], rawMargins[accountId]["startingMargin"]["nano"]),
4276                    "min": NanoToFloat(rawMargins[accountId]["minimalMargin"]["units"], rawMargins[accountId]["minimalMargin"]["nano"]),
4277                    "level": NanoToFloat(rawMargins[accountId]["fundsSufficiencyLevel"]["units"], rawMargins[accountId]["fundsSufficiencyLevel"]["nano"]),
4278                    "missing": NanoToFloat(rawMargins[accountId]["amountOfMissingFunds"]["units"], rawMargins[accountId]["amountOfMissingFunds"]["nano"]),
4279                }
4280
4281            else:
4282                margins[accountId] = {}  # Server response: margin status is disabled for current accountId
4283
4284        unary = {}  # unary-connection limits
4285        for item in rawTariffLimits["unaryLimits"]:
4286            if item["limitPerMinute"] in unary.keys():
4287                unary[item["limitPerMinute"]].extend(item["methods"])
4288
4289            else:
4290                unary[item["limitPerMinute"]] = item["methods"]
4291
4292        stream = {}  # stream-connection limits
4293        for item in rawTariffLimits["streamLimits"]:
4294            if item["limit"] in stream.keys():
4295                stream[item["limit"]].extend(item["streams"])
4296
4297            else:
4298                stream[item["limit"]] = item["streams"]
4299
4300        # This is dict with parsed limits of current tariff (connections, API methods etc.):
4301        limits = {
4302            "unary": unary,
4303            "stream": stream,
4304        }
4305
4306        # Raw and parsed data as an output result:
4307        view = {
4308            "rawUserInfo": rawUserInfo,
4309            "rawAccounts": rawAccounts,
4310            "rawMargins": rawMargins,
4311            "rawTariffLimits": rawTariffLimits,
4312            "stat": {
4313                "userInfo": userInfo,
4314                "accounts": accounts,
4315                "margins": margins,
4316                "limits": limits,
4317            },
4318        }
4319
4320        # --- Prepare text table with user information in human-readable format:
4321        if show:
4322            info = [
4323                "# Full user information\n\n",
4324                "* **Actual date:** [{} UTC]\n\n".format(datetime.now(tzutc()).strftime(TKS_PRINT_DATE_TIME_FORMAT)),
4325                "## Common information\n\n",
4326                "* **Qualified user:** {}\n".format(view["stat"]["userInfo"]["qualified"]),
4327                "* **Tariff name:** {}\n".format(view["stat"]["userInfo"]["tariff"]),
4328                "* **Premium user:** {}\n".format(view["stat"]["userInfo"]["premium"]),
4329                "* **Allowed to work with instruments:**\n{}\n".format("".join(["  - {}\n".format(item) for item in view["stat"]["userInfo"]["allowed"]])),
4330                "\n## User accounts\n\n",
4331            ]
4332
4333            for account in view["stat"]["accounts"].keys():
4334                info.extend([
4335                    "### ID: [{}]\n\n".format(account),
4336                    "| Parameters           | Values                                                       |\n",
4337                    "|----------------------|--------------------------------------------------------------|\n",
4338                    "| Account type:        | {:<60} |\n".format(view["stat"]["accounts"][account]["type"]),
4339                    "| Account name:        | {:<60} |\n".format(view["stat"]["accounts"][account]["name"]),
4340                    "| Account status:      | {:<60} |\n".format(view["stat"]["accounts"][account]["status"]),
4341                    "| Access level:        | {:<60} |\n".format(view["stat"]["accounts"][account]["access"]),
4342                    "| Date opened:         | {:<60} |\n".format(view["stat"]["accounts"][account]["opened"]),
4343                    "| Date closed:         | {:<60} |\n".format(view["stat"]["accounts"][account]["closed"]),
4344                ])
4345
4346                if margins[account]:
4347                    info.extend([
4348                        "| Margin status:       | Enabled                                                      |\n",
4349                        "| - Liquid portfolio:  | {:<60} |\n".format("{} {}".format(margins[account]["liquid"], margins[account]["currency"])),
4350                        "| - Margin starting:   | {:<60} |\n".format("{} {}".format(margins[account]["start"], margins[account]["currency"])),
4351                        "| - Margin minimum:    | {:<60} |\n".format("{} {}".format(margins[account]["min"], margins[account]["currency"])),
4352                        "| - Sufficiency level: | {:<60} |\n".format("{:.2f} ({:.2f}%)".format(margins[account]["level"], margins[account]["level"] * 100)),
4353                        "| - Missing funds:     | {:<60} |\n\n".format("{} {}".format(margins[account]["missing"], margins[account]["currency"])),
4354                    ])
4355
4356                else:
4357                    info.append("| Margin status:       | Disabled                                                     |\n\n")
4358
4359            info.extend([
4360                "\n## Current user tariff limits\n",
4361                "\nSee also:\n",
4362                "* Tinkoff limit policy: https://tinkoff.github.io/investAPI/limits/\n",
4363                "* Tinkoff Invest API: https://tinkoff.github.io/investAPI/\n",
4364                "  - More about REST API requests: https://tinkoff.github.io/investAPI/swagger-ui/\n",
4365                "  - More about gRPC requests for stream connections: https://tinkoff.github.io/investAPI/grpc/\n",
4366                "\n### Unary limits\n",
4367            ])
4368
4369            if unary:
4370                for key, values in sorted(unary.items()):
4371                    info.append("\n* Max requests per minute: {}\n".format(key))
4372
4373                    for value in values:
4374                        info.append("  - {}\n".format(value))
4375
4376            else:
4377                info.append("\nNot available\n")
4378
4379            info.append("\n### Stream limits\n")
4380
4381            if stream:
4382                for key, values in sorted(stream.items()):
4383                    info.append("\n* Max stream connections: {}\n".format(key))
4384
4385                    for value in values:
4386                        info.append("  - {}\n".format(value))
4387
4388            else:
4389                info.append("\nNot available\n")
4390
4391            infoText = "".join(info)
4392
4393            uLogger.info(infoText)
4394
4395            if self.userInfoFile:
4396                with open(self.userInfoFile, "w", encoding="UTF-8") as fH:
4397                    fH.write(infoText)
4398
4399                uLogger.info("User data was saved to file: [{}]".format(os.path.abspath(self.userInfoFile)))
4400
4401        return view
4402
4403
4404class Args:
4405    """
4406    If `Main()` function is imported as module, then this class used to convert arguments from **kwargs as object.
4407    """
4408    def __init__(self, **kwargs):
4409        self.__dict__.update(kwargs)
4410
4411    def __getattr__(self, item):
4412        return None
4413
4414
4415def ParseArgs():
4416    """This function get and parse command line keys."""
4417    parser = ArgumentParser()  # command-line string parser
4418
4419    parser.description = "TKSBrokerAPI is a trading platform for automation on Python to simplify the implementation of trading scenarios and work with Tinkoff Invest API server via the REST protocol. See examples: https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README_EN.md"
4420    parser.usage = "\n/as module/ python TKSBrokerAPI.py [some options] [one command]\n/as CLI tool/ tksbrokerapi [some options] [one command]"
4421
4422    # --- options:
4423
4424    parser.add_argument("--no-cache", action="store_true", default=False, help="Option: not use local cache `dump.json`, but update raw instruments data when starting the platform. `False` by default.")
4425    parser.add_argument("--token", type=str, help="Option: Tinkoff service's api key. If not set then used environment variable `TKS_API_TOKEN`. See how to use: https://tinkoff.github.io/investAPI/token/")
4426    parser.add_argument("--account-id", type=str, default=None, help="Option: string with an user numeric account ID in Tinkoff Broker. It can be found in any broker's reports (see the contract number). Also, this variable can be set from environment variable `TKS_ACCOUNT_ID`.")
4427
4428    parser.add_argument("--ticker", "-t", type=str, help="Option: instrument's ticker, e.g. `IBM`, `YNDX`, `GOOGL` etc. Use alias for `USD000UTSTOM` simple as `USD`, `EUR_RUB__TOM` as `EUR`.")
4429    parser.add_argument("--figi", "-f", type=str, help="Option: instrument's FIGI, e.g. `BBG006L8G4H1` (for `YNDX`).")
4430
4431    parser.add_argument("--depth", type=int, default=1, help="Option: Depth of Market (DOM) can be >=1, 1 by default.")
4432    parser.add_argument("--no-cancelled", "--no-canceled", action="store_true", default=False, help="Option: remove information about cancelled operations from the deals report by the `--deals` key. `False` by default.")
4433
4434    parser.add_argument("--output", type=str, default=None, help="Option: replace default paths to output files for some commands. If `None` then used default files.")
4435
4436    parser.add_argument("--interval", type=str, default="hour", help="Option: available values are `1min`, `5min`, `15min`, `hour` and `day`. Used only with `--history` key. This is time period of one candle. Default: `hour` for every history candles.")
4437    parser.add_argument("--only-missing", action="store_true", default=False, help="Option: if history file define by `--output` key then add only last missing candles, do not request all history length. `False` by default.")
4438    parser.add_argument("--csv-sep", type=str, default=",", help="Option: separator if csv-file is used, `,` by default.")
4439
4440    parser.add_argument("--debug-level", "--log-level", "--verbosity", "-v", type=int, default=20, help="Option: showing STDOUT messages of minimal debug level, e.g. 10 = DEBUG, 20 = INFO, 30 = WARNING, 40 = ERROR, 50 = CRITICAL. INFO (20) by default.")
4441    parser.add_argument("--more", "--more-debug", action="store_true", default=False, help="Option: `--debug-level` key only switch log level verbosity, but in addition `--more` key enable all debug information, such as net request and response headers in all methods.")
4442
4443    # --- commands:
4444
4445    parser.add_argument("--version", "--ver", action="store_true", help="Action: shows current semantic version, looks like `major.minor.buildnumber`. If TKSBrokerAPI not installed via pip, then used local build number `.dev0`.")
4446
4447    parser.add_argument("--list", "-l", action="store_true", help="Action: get and print all available instruments and some information from broker server. Also, you can define `--output` key to save list of instruments to file, default: `instruments.md`.")
4448    parser.add_argument("--list-xlsx", "-x", action="store_true", help="Action: get all available instruments from server for current account and save raw data into xlsx-file for further used by data scientists or stock analytics, default: `dump.xlsx`.")
4449    parser.add_argument("--bonds-xlsx", "-b", type=str, nargs="*", help="Action: get all available bonds if only key present or list of bonds with FIGIs or tickers and transform it to the wider Pandas DataFrame with more information about bonds: main info, current prices, bonds payment calendar, coupon yields, current yields and some statistics etc. And then export data to XLSX-file, default: `ext-bonds.xlsx` or you can change it with `--output` key. WARNING! This is too long operation if a lot of bonds requested from broker server.")
4450    parser.add_argument("--search", "-s", type=str, nargs=1, help="Action: search for an instruments by part of the name, ticker or FIGI. Also, you can define `--output` key to save results to file, default: `search-results.md`.")
4451    parser.add_argument("--info", "-i", action="store_true", help="Action: get information from broker server about instrument by it's ticker or FIGI. `--ticker` key or `--figi` key must be defined!")
4452    parser.add_argument("--calendar", "-c", type=str, nargs="*", help="Action: show bonds payment calendar as a table. Calendar build for one or more tickers or FIGIs, or for all bonds if only key present. If the `--output` key present then calendar saves to file, default: `calendar.md`. Also, created XLSX-file with bond payments calendar for further used by data scientists or stock analytics, `calendar.xlsx` by default. WARNING! This is too long operation if a lot of bonds requested from broker server.")
4453    parser.add_argument("--price", action="store_true", help="Action: show actual price list for current instrument. Also, you can use `--depth` key. `--ticker` key or `--figi` key must be defined!")
4454    parser.add_argument("--prices", "-p", type=str, nargs="+", help="Action: get and print current prices for list of given instruments (by it's tickers or by FIGIs). WARNING! This is too long operation if you request a lot of instruments! Also, you can define `--output` key to save list of prices to file, default: `prices.md`.")
4455
4456    parser.add_argument("--overview", "-o", action="store_true", help="Action: shows all open positions, orders and some statistics. Also, you can define `--output` key to save this information to file, default: `overview.md`.")
4457    parser.add_argument("--overview-digest", action="store_true", help="Action: shows a short digest of the portfolio status. Also, you can define `--output` key to save this information to file, default: `overview-digest.md`.")
4458    parser.add_argument("--overview-positions", action="store_true", help="Action: shows only open positions. Also, you can define `--output` key to save this information to file, default: `overview-positions.md`.")
4459    parser.add_argument("--overview-orders", action="store_true", help="Action: shows only sections of open limits and stop orders. Also, you can define `--output` key to save orders to file, default: `overview-orders.md`.")
4460    parser.add_argument("--overview-analytics", action="store_true", help="Action: shows only the analytics section and the distribution of the portfolio by various categories. Also, you can define `--output` key to save this information to file, default: `overview-analytics.md`.")
4461
4462    parser.add_argument("--deals", "-d", type=str, nargs="*", help="Action: show all deals between two given dates. Start day may be an integer number: -1, -2, -3 days ago. Also, you can use keywords: `today`, `yesterday` (-1), `week` (-7), `month` (-30) and `year` (-365). Dates format must be: `%%Y-%%m-%%d`, e.g. 2020-02-03. With `--no-cancelled` key information about cancelled operations will be removed from the deals report. Also, you can define `--output` key to save all deals to file, default: `deals.md`.")
4463    parser.add_argument("--history", type=str, nargs="*", help="Action: get last history candles of the current instrument defined by `--ticker` or `--figi` (FIGI id) keys. History returned between two given dates: `start` and `end`. Minimum requested date in the past is `1970-01-01`. This action may be used together with the `--render-chart` key. Also, you can define `--output` key to save history candlesticks to file.")
4464    parser.add_argument("--load-history", type=str, help="Action: try to load history candles from given csv-file as a Pandas Dataframe and print it in to the console. This action may be used together with the `--render-chart` key.")
4465    parser.add_argument("--render-chart", type=str, help="Action: render candlesticks chart. This key may only used with `--history` or `--load-history` together. Action has 1 parameter with two possible string values: `interact` (`i`) or `non-interact` (`ni`).")
4466
4467    parser.add_argument("--trade", nargs="*", help="Action: universal action to open market position for defined ticker or FIGI. You must specify 1-5 parameters: [direction `Buy` or `Sell`] [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`]. See examples in readme.")
4468    parser.add_argument("--buy", nargs="*", help="Action: immediately open BUY market position at the current price for defined ticker or FIGI. You must specify 0-4 parameters: [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`].")
4469    parser.add_argument("--sell", nargs="*", help="Action: immediately open SELL market position at the current price for defined ticker or FIGI. You must specify 0-4 parameters: [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`].")
4470
4471    parser.add_argument("--order", nargs="*", help="Action: universal action to open limit or stop-order in any directions. You must specify 4-7 parameters: [direction `Buy` or `Sell`] [order type `Limit` or `Stop`] [lots] [target price] [maybe for stop-order: [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`]]. See examples in readme.")
4472    parser.add_argument("--buy-limit", type=float, nargs=2, help="Action: open pending BUY limit-order (below current price). You must specify only 2 parameters: [lots] [target price] to open BUY limit-order. If you try to create `Buy` limit-order above current price then broker immediately open `Buy` market order, such as if you do simple `--buy` operation!")
4473    parser.add_argument("--sell-limit", type=float, nargs=2, help="Action: open pending SELL limit-order (above current price). You must specify only 2 parameters: [lots] [target price] to open SELL limit-order. If you try to create `Sell` limit-order below current price then broker immediately open `Sell` market order, such as if you do simple `--sell` operation!")
4474    parser.add_argument("--buy-stop", nargs="*", help="Action: open BUY stop-order. You must specify at least 2 parameters: [lots] [target price] to open BUY stop-order. In additional you can specify 3 parameters for stop-order: [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`]. When current price will go up or down to target price value then broker opens a limit order. Stop loss order always executed by market price.")
4475    parser.add_argument("--sell-stop", nargs="*", help="Action: open SELL stop-order. You must specify at least 2 parameters: [lots] [target price] to open SELL stop-order. In additional you can specify 3 parameters for stop-order: [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%%Y-%%m-%%d %%H:%%M:%%S`]. When current price will go up or down to target price value then broker opens a limit order. Stop loss order always executed by market price.")
4476    # parser.add_argument("--buy-limit-order-grid", type=str, nargs="*", help="Action: open grid of pending BUY limit-orders (below current price). Parameters format: l(ots)=[L_int,...] p(rices)=[P_float,...]. Counts of values in lots and prices lists must be equals!")
4477    # parser.add_argument("--sell-limit-order-grid", type=str, nargs="*", help="Action: open grid of pending SELL limit-orders (above current price). Parameters format: l(ots)=[L_int,...] p(rices)=[P_float,...]. Counts of values in lots and prices lists must be equals!")
4478
4479    parser.add_argument("--close-order", "--cancel-order", type=str, nargs=1, help="Action: close only one order by it's `orderId` or `stopOrderId`. You can find out the meaning of these IDs using the key `--overview`.")
4480    parser.add_argument("--close-orders", "--cancel-orders", type=str, nargs="+", help="Action: close one or list of orders by it's `orderId` or `stopOrderId`. You can find out the meaning of these IDs using the key `--overview`.")
4481    parser.add_argument("--close-trade", "--cancel-trade", action="store_true", help="Action: close only one position for instrument defined by `--ticker` (high priority) or `--figi` keys, including for currencies tickers.")
4482    parser.add_argument("--close-trades", "--cancel-trades", type=str, nargs="+", help="Action: close positions for list of tickers or FIGIs, including for currencies tickers or FIGIs.")
4483    parser.add_argument("--close-all", "--cancel-all", type=str, nargs="*", help="Action: close all available (not blocked) opened trades and orders, excluding for currencies. Also you can select one or more keywords case insensitive to specify trades type: `orders`, `shares`, `bonds`, `etfs` and `futures`, but not `currencies`. Currency positions you must closes manually using `--buy`, `--sell`, `--close-trade` or `--close-trades` operations.")
4484
4485    parser.add_argument("--limits", "--withdrawal-limits", "-w", action="store_true", help="Action: show table of funds available for withdrawal for current `accountId`. You can change `accountId` with the key `--account-id`. Also, you can define `--output` key to save this information to file, default: `limits.md`.")
4486    parser.add_argument("--user-info", "-u", action="store_true", help="Action: show all available user's data (`accountId`s, common user information, margin status and tariff connections limit). Also, you can define `--output` key to save this information to file, default: `user-info.md`.")
4487    parser.add_argument("--account", "--accounts", "-a", action="store_true", help="Action: show simple table with all available user accounts. Also, you can define `--output` key to save this information to file, default: `accounts.md`.")
4488
4489    cmdArgs = parser.parse_args()
4490    return cmdArgs
4491
4492
4493def Main(**kwargs):
4494    """
4495    Main function for work with TKSBrokerAPI in the console.
4496
4497    See examples:
4498    - in english: https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README_EN.md
4499    - in russian: https://github.com/Tim55667757/TKSBrokerAPI/blob/master/README.md
4500    """
4501    args = Args(**kwargs) if kwargs else ParseArgs()  # get and parse command-line parameters or use **kwarg parameters
4502
4503    if args.debug_level:
4504        uLogger.level = 10  # always debug level by default
4505        uLogger.handlers[0].level = args.debug_level  # level for STDOUT
4506
4507    exitCode = 0
4508    start = datetime.now(tzutc())
4509    uLogger.debug("=-" * 60)
4510    uLogger.debug(">>> TKSBrokerAPI module started at: [{}] UTC, it is [{}] local time".format(
4511        start.strftime(TKS_PRINT_DATE_TIME_FORMAT),
4512        start.astimezone(tzlocal()).strftime(TKS_PRINT_DATE_TIME_FORMAT),
4513    ))
4514
4515    # trying to calculate full current version:
4516    buildVersion = __version__
4517    try:
4518        v = version("tksbrokerapi")
4519        buildVersion = v if v.startswith(buildVersion) else buildVersion + ".dev0"  # set version as major.minor.dev0 if run as local build or local script
4520
4521    except Exception:
4522        buildVersion = __version__ + ".dev0"  # if an errors occurred then also set version as major.minor.dev0
4523
4524    uLogger.debug("TKSBrokerAPI major.minor.build version used: [{}]".format(buildVersion))
4525    uLogger.debug("Host CPU count: [{}]".format(CPU_COUNT))
4526
4527    try:
4528        if args.version:
4529            print("TKSBrokerAPI {}".format(buildVersion))
4530            uLogger.debug("User requested current TKSBrokerAPI major.minor.build version: [{}]".format(buildVersion))
4531
4532        else:
4533            # Init class for trading with Tinkoff Broker: TODO: rename `server` to `trader`
4534            server = TinkoffBrokerServer(
4535                token=args.token,
4536                accountId=args.account_id,
4537                useCache=not args.no_cache,
4538            )
4539
4540            # --- set some options:
4541
4542            if args.more:
4543                server.moreDebug = True
4544                uLogger.warning("More debug info mode is enabled! See network requests, responses and its headers in the full log or run TKSBrokerAPI platform with the `--verbosity 10` to show theres in console.")
4545
4546            if args.ticker:
4547                if args.ticker in server.aliasesKeys:
4548                    server.ticker = server.aliases[args.ticker]  # Replace some tickers with its aliases
4549
4550                else:
4551                    server.ticker = args.ticker
4552
4553            if args.figi:
4554                server.figi = args.figi
4555
4556            if args.depth is not None:
4557                server.depth = args.depth
4558
4559            # --- do one command:
4560
4561            if args.list:
4562                if args.output is not None:
4563                    server.instrumentsFile = args.output
4564
4565                server.ShowInstrumentsInfo(show=True)
4566
4567            elif args.list_xlsx:
4568                server.DumpInstrumentsAsXLSX(forceUpdate=False)
4569
4570            elif args.bonds_xlsx is not None:
4571                if args.output is not None:
4572                    server.bondsXLSXFile = args.output
4573
4574                if len(args.bonds_xlsx) == 0:
4575                    server.ExtendBondsData(instruments=server.iList["Bonds"].keys(), xlsx=True)  # request bonds with all available tickers
4576
4577                else:
4578                    server.ExtendBondsData(instruments=args.bonds_xlsx, xlsx=True)  # request list of given bonds
4579
4580            elif args.search:
4581                if args.output is not None:
4582                    server.searchResultsFile = args.output
4583
4584                server.SearchInstruments(pattern=args.search[0], show=True)
4585
4586            elif args.info:
4587                if not (args.ticker or args.figi):
4588                    uLogger.error("`--ticker` key or `--figi` key is required for this operation!")
4589                    raise Exception("Ticker or FIGI required")
4590
4591                if args.output is not None:
4592                    server.infoFile = args.output
4593
4594                if args.ticker:
4595                    server.SearchByTicker(requestPrice=True, show=True)  # show info and current prices by ticker name
4596
4597                else:
4598                    server.SearchByFIGI(requestPrice=True, show=True)  # show info and current prices by FIGI id
4599
4600            elif args.calendar is not None:
4601                if args.output is not None:
4602                    server.calendarFile = args.output
4603
4604                if len(args.calendar) == 0:
4605                    bondsData = server.ExtendBondsData(instruments=server.iList["Bonds"].keys(), xlsx=False)  # request bonds with all available tickers
4606
4607                else:
4608                    bondsData = server.ExtendBondsData(instruments=args.calendar, xlsx=False)  # request list of given bonds
4609
4610                server.ShowBondsCalendar(extBonds=bondsData, show=True)  # shows bonds payment calendar only
4611
4612            elif args.price:
4613                if not (args.ticker or args.figi):
4614                    uLogger.error("`--ticker` key or `--figi` key is required for this operation!")
4615                    raise Exception("Ticker or FIGI required")
4616
4617                server.GetCurrentPrices(show=True)
4618
4619            elif args.prices is not None:
4620                if args.output is not None:
4621                    server.pricesFile = args.output
4622
4623                server.GetListOfPrices(instruments=args.prices, show=True)  # WARNING: too long wait for a lot of instruments prices
4624
4625            elif args.overview:
4626                if args.output is not None:
4627                    server.overviewFile = args.output
4628
4629                server.Overview(show=True, details="full")
4630
4631            elif args.overview_digest:
4632                if args.output is not None:
4633                    server.overviewDigestFile = args.output
4634
4635                server.Overview(show=True, details="digest")
4636
4637            elif args.overview_positions:
4638                if args.output is not None:
4639                    server.overviewPositionsFile = args.output
4640
4641                server.Overview(show=True, details="positions")
4642
4643            elif args.overview_orders:
4644                if args.output is not None:
4645                    server.overviewOrdersFile = args.output
4646
4647                server.Overview(show=True, details="orders")
4648
4649            elif args.overview_analytics:
4650                if args.output is not None:
4651                    server.overviewAnalyticsFile = args.output
4652
4653                server.Overview(show=True, details="analytics")
4654
4655            elif args.deals is not None:
4656                if args.output is not None:
4657                    server.reportFile = args.output
4658
4659                if 0 <= len(args.deals) < 3:
4660                    server.Deals(
4661                        start=args.deals[0] if len(args.deals) >= 1 else None,
4662                        end=args.deals[1] if len(args.deals) == 2 else None,
4663                        show=True,  # Always show deals report in console
4664                        showCancelled=not args.no_cancelled,  # If --no-cancelled key then remove cancelled operations from the deals report. False by default.
4665                    )
4666
4667                else:
4668                    uLogger.error("You must specify 0-2 parameters: [DATE_START] [DATE_END]")
4669                    raise Exception("Incorrect value")
4670
4671            elif args.history is not None:
4672                if args.output is not None:
4673                    server.historyFile = args.output
4674
4675                if 0 <= len(args.history) < 3:
4676                    dataReceived = server.History(
4677                        start=args.history[0] if len(args.history) >= 1 else None,
4678                        end=args.history[1] if len(args.history) == 2 else None,
4679                        interval="hour" if args.interval is None or not args.interval else args.interval,
4680                        onlyMissing=False if args.only_missing is None or not args.only_missing else args.only_missing,
4681                        csvSep="," if args.csv_sep is None or not args.csv_sep else args.csv_sep,
4682                        show=True,  # shows all downloaded candles in console
4683                    )
4684
4685                    if args.render_chart is not None and dataReceived is not None:
4686                        iChart = False if args.render_chart.lower() == "ni" or args.render_chart.lower() == "non-interact" else True
4687
4688                        server.ShowHistoryChart(
4689                            candles=dataReceived,
4690                            interact=iChart,
4691                            openInBrowser=False,  # False by default, to avoid issues with `permissions denied` to html-file.
4692                        )
4693
4694                else:
4695                    uLogger.error("You must specify 0-2 parameters: [DATE_START] [DATE_END]")
4696                    raise Exception("Incorrect value")
4697
4698            elif args.load_history is not None:
4699                histData = server.LoadHistory(filePath=args.load_history)  # load data from file and show history in console
4700
4701                if args.render_chart is not None and histData is not None:
4702                    iChart = False if args.render_chart.lower() == "ni" or args.render_chart.lower() == "non-interact" else True
4703                    server.ticker = os.path.basename(args.load_history)  # use filename as ticker name for PriceGenerator's chart
4704
4705                    server.ShowHistoryChart(
4706                        candles=histData,
4707                        interact=iChart,
4708                        openInBrowser=False,  # False by default, to avoid issues with `permissions denied` to html-file.
4709                    )
4710
4711            elif args.trade is not None:
4712                if 1 <= len(args.trade) <= 5:
4713                    server.Trade(
4714                        operation=args.trade[0],
4715                        lots=int(args.trade[1]) if len(args.trade) >= 2 else 1,
4716                        tp=float(args.trade[2]) if len(args.trade) >= 3 else 0.,
4717                        sl=float(args.trade[3]) if len(args.trade) >= 4 else 0.,
4718                        expDate=args.trade[4] if len(args.trade) == 5 else "Undefined",
4719                    )
4720
4721                else:
4722                    uLogger.error("You must specify 1-5 parameters to open trade: [direction `Buy` or `Sell`] [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%Y-%m-%d %H:%M:%S`]. See: `python TKSBrokerAPI.py --help`")
4723
4724            elif args.buy is not None:
4725                if 0 <= len(args.buy) <= 4:
4726                    server.Buy(
4727                        lots=int(args.buy[0]) if len(args.buy) >= 1 else 1,
4728                        tp=float(args.buy[1]) if len(args.buy) >= 2 else 0.,
4729                        sl=float(args.buy[2]) if len(args.buy) >= 3 else 0.,
4730                        expDate=args.buy[3] if len(args.buy) == 4 else "Undefined",
4731                    )
4732
4733                else:
4734                    uLogger.error("You must specify 0-4 parameters to open buy position: [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%Y-%m-%d %H:%M:%S`]. See: `python TKSBrokerAPI.py --help`")
4735
4736            elif args.sell is not None:
4737                if 0 <= len(args.sell) <= 4:
4738                    server.Sell(
4739                        lots=int(args.sell[0]) if len(args.sell) >= 1 else 1,
4740                        tp=float(args.sell[1]) if len(args.sell) >= 2 else 0.,
4741                        sl=float(args.sell[2]) if len(args.sell) >= 3 else 0.,
4742                        expDate=args.sell[3] if len(args.sell) == 4 else "Undefined",
4743                    )
4744
4745                else:
4746                    uLogger.error("You must specify 0-4 parameters to open sell position: [lots, >= 1] [take profit, >= 0] [stop loss, >= 0] [expiration date for TP/SL orders, Undefined|`%Y-%m-%d %H:%M:%S`]. See: `python TKSBrokerAPI.py --help`")
4747
4748            elif args.order:
4749                if 4 <= len(args.order) <= 7:
4750                    server.Order(
4751                        operation=args.order[0],
4752                        orderType=args.order[1],
4753                        lots=int(args.order[2]),
4754                        targetPrice=float(args.order[3]),
4755                        limitPrice=float(args.order[4]) if len(args.order) >= 5 else 0.,
4756                        stopType=args.order[5] if len(args.order) >= 6 else "Limit",
4757                        expDate=args.order[6] if len(args.order) == 7 else "Undefined",
4758                    )
4759
4760                else:
4761                    uLogger.error("You must specify 4-7 parameters to open order: [direction `Buy` or `Sell`] [order type `Limit` or `Stop`] [lots] [target price] [maybe for stop-order: [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%Y-%m-%d %H:%M:%S`]]. See: `python TKSBrokerAPI.py --help`")
4762
4763            elif args.buy_limit:
4764                server.BuyLimit(lots=int(args.buy_limit[0]), targetPrice=args.buy_limit[1])
4765
4766            elif args.sell_limit:
4767                server.SellLimit(lots=int(args.sell_limit[0]), targetPrice=args.sell_limit[1])
4768
4769            elif args.buy_stop:
4770                if 2 <= len(args.buy_stop) <= 7:
4771                    server.BuyStop(
4772                        lots=int(args.buy_stop[0]),
4773                        targetPrice=float(args.buy_stop[1]),
4774                        limitPrice=float(args.buy_stop[2]) if len(args.buy_stop) >= 3 else 0.,
4775                        stopType=args.buy_stop[3] if len(args.buy_stop) >= 4 else "Limit",
4776                        expDate=args.buy_stop[4] if len(args.buy_stop) == 5 else "Undefined",
4777                    )
4778
4779                else:
4780                    uLogger.error("You must specify 2-5 parameters for buy stop-order: [lots] [target price] [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%Y-%m-%d %H:%M:%S`]. See: `python TKSBrokerAPI.py --help`")
4781
4782            elif args.sell_stop:
4783                if 2 <= len(args.sell_stop) <= 7:
4784                    server.SellStop(
4785                        lots=int(args.sell_stop[0]),
4786                        targetPrice=float(args.sell_stop[1]),
4787                        limitPrice=float(args.sell_stop[2]) if len(args.sell_stop) >= 3 else 0.,
4788                        stopType=args.sell_stop[3] if len(args.sell_stop) >= 4 else "Limit",
4789                        expDate=args.sell_stop[4] if len(args.sell_stop) == 5 else "Undefined",
4790                    )
4791
4792                else:
4793                    uLogger.error("You must specify 2-5 parameters for sell stop-order: [lots] [target price] [limit price, >= 0] [stop type, Limit|SL|TP] [expiration date, Undefined|`%Y-%m-%d %H:%M:%S`]. See: python TKSBrokerAPI.py --help")
4794
4795            # elif args.buy_order_grid is not None:
4796            #     # update order grid work with api v2
4797            #     if len(args.buy_order_grid) == 2:
4798            #         orderParams = server.ParseOrderParameters(operation="Buy", **dict(kw.split('=') for kw in args.buy_order_grid))
4799            #
4800            #         for order in orderParams:
4801            #             server.Order(operation="Buy", lots=order["lot"], price=order["price"])
4802            #
4803            #     else:
4804            #         uLogger.error("To open grid of pending BUY limit-orders (below current price) you must specified 2 parameters: l(ots)=[L_int,...] p(rices)=[P_float,...]. See: `python TKSBrokerAPI.py --help`")
4805            #
4806            # elif args.sell_order_grid is not None:
4807            #     # update order grid work with api v2
4808            #     if len(args.sell_order_grid) >= 2:
4809            #         orderParams = server.ParseOrderParameters(operation="Sell", **dict(kw.split('=') for kw in args.sell_order_grid))
4810            #
4811            #         for order in orderParams:
4812            #             server.Order(operation="Sell", lots=order["lot"], price=order["price"])
4813            #
4814            #     else:
4815            #         uLogger.error("To open grid of pending SELL limit-orders (above current price) you must specified 2 parameters: l(ots)=[L_int,...] p(rices)=[P_float,...]. See: `python TKSBrokerAPI.py --help`")
4816
4817            elif args.close_order is not None:
4818                server.CloseOrders(args.close_order)  # close only one order
4819
4820            elif args.close_orders is not None:
4821                server.CloseOrders(args.close_orders)  # close list of orders
4822
4823            elif args.close_trade:
4824                if not (args.ticker or args.figi):
4825                    uLogger.error("`--ticker` key or `--figi` key is required for this operation!")
4826                    raise Exception("Ticker or FIGI required")
4827
4828                if args.ticker:
4829                    server.CloseTrades([args.ticker])  # close only one trade by ticker (priority)
4830
4831                else:
4832                    server.CloseTrades([args.figi])  # close only one trade by FIGI
4833
4834            elif args.close_trades is not None:
4835                server.CloseTrades(args.close_trades)  # close trades for list of tickers
4836
4837            elif args.close_all is not None:
4838                server.CloseAll(*args.close_all)
4839
4840            elif args.limits:
4841                if args.output is not None:
4842                    server.withdrawalLimitsFile = args.output
4843
4844                server.OverviewLimits(show=True)
4845
4846            elif args.user_info:
4847                if args.output is not None:
4848                    server.userInfoFile = args.output
4849
4850                server.OverviewUserInfo(show=True)
4851
4852            elif args.account:
4853                if args.output is not None:
4854                    server.userAccountsFile = args.output
4855
4856                server.OverviewAccounts(show=True)
4857
4858            else:
4859                uLogger.error("There is no command to execute! One of the possible commands must be selected. See help with `--help` key.")
4860                raise Exception("There is no command to execute")
4861
4862    except Exception:
4863        trace = tb.format_exc()
4864        for e in ["socket.gaierror", "nodename nor servname provided", "or not known", "NewConnectionError", "[Errno 8]", "Failed to establish a new connection"]:
4865            if e in trace:
4866                uLogger.error("Check your Internet connection! Failed to establish connection to broker server!")
4867                break
4868
4869        uLogger.debug(trace)
4870        uLogger.debug("Please, check issues or request a new one at https://github.com/Tim55667757/TKSBrokerAPI/issues")
4871        exitCode = 255  # an error occurred, must be open a ticket for this issue
4872
4873    finally:
4874        finish = datetime.now(tzutc())
4875
4876        if exitCode == 0:
4877            if args.more:
4878                uLogger.debug("All operations were finished success (summary code is 0).")
4879
4880        else:
4881            uLogger.error("An issue occurred with TKSBrokerAPI module! See full debug log in [{}] or run TKSBrokerAPI once again with the key `--debug-level 10`. Summary code: {}".format(
4882                os.path.abspath(uLog.defaultLogFile), exitCode,
4883            ))
4884
4885        uLogger.debug(">>> TKSBrokerAPI module work duration: [{}]".format(finish - start))
4886        uLogger.debug(">>> TKSBrokerAPI module finished: [{} UTC], it is [{}] local time".format(
4887            finish.strftime(TKS_PRINT_DATE_TIME_FORMAT),
4888            finish.astimezone(tzlocal()).strftime(TKS_PRINT_DATE_TIME_FORMAT),
4889        ))
4890        uLogger.debug("=-" * 60)
4891
4892        if not kwargs:
4893            sys.exit(exitCode)
4894
4895        else:
4896            return exitCode
4897
4898
4899if __name__ == "__main__":
4900    Main()